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
    Back to top

    Creation

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

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

    Parameters:

    1

    string

    optional, default value=""

    campaign name

    Returns:

    1. campaign_manager campaign manager

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

    Back to top

    Usage

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

    Example - Specification:

    cm:<function_name>(<args>)

    Example - Creation and Usage:

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

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

    Campaign Name

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

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

    Parameters:

    1

    string

    campaign name

    Returns:

    1. nil

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

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

    Returns:

    1. string campaign name

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

    Back to top

    Loading Campaign Script Files

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

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

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

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

    Returns:

    1. string campaign folder path

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

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

    Returns:

    1. nil

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

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

    Returns:

    1. nil

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

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

    Parameters:

    1

    string

    script name

    2

    boolean

    optional, default value=false

    single player only

    Returns:

    1. nil

    Example - Loading faction script:

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

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

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

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

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

    Parameters:

    1

    string

    Filename subset of script file(s) to load.

    2

    string

    optional, default value="script"

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

    Returns:

    1. nil

    Example:

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

    Example:

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

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

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

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

    Back to top

    Loading Game

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

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

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

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

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

    Example:

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

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

    Parameters:

    1

    function

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

    Returns:

    1. nil

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

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

    Parameters:

    1

    string

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

    2

    object

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

    3

    userdata

    Context object supplied by the LoadingGame event.

    Returns:

    1. nil

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

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

    Parameters:

    1

    string

    value name

    Returns:

    1. object value

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

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

    Parameters:

    1

    string

    value name

    2

    function

    generator callback

    Returns:

    1. object value

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

    Back to top

    Saving Game

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

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

    Parameters:

    1

    function

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

    Returns:

    1. nil

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

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

    Parameters:

    1

    function

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

    Returns:

    1. nil

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

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

    Parameters:

    1

    string

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

    2

    object

    Value to save.

    3

    userdata

    Context object supplied by the SavingGame event.

    Returns:

    1. nil

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

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

    Parameters:

    1

    string

    Value name.

    2

    object

    Value. Can be a boolean, number or string.

    Returns:

    1. nil

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

    campaign_manager:save([function callback], [boolean lock afterwards])
    Instructs the campaign game to save at the next opportunity. An optional completion callback may be supplied.

    Parameters:

    1

    function

    optional, default value=nil

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

    2

    boolean

    optional, default value=false

    Lock saving functionality after saving is completed.

    Returns:

    1. nil

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

    Back to top

    Game Destroyed

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

    Parameters:

    1

    function

    callback

    Returns:

    1. nil

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

    Back to top

    First Tick

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

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

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

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

    Parameters:

    1

    function

    callback

    Returns:

    1. nil

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

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

    Parameters:

    1

    function

    callback

    Returns:

    1. nil

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

    campaign_manager:add_first_tick_callback_sp_new(function callback)
    Registers a function to be called when the first tick occurs in a new singleplayer game.

    Parameters:

    1

    function

    callback

    Returns:

    1. nil

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

    campaign_manager:add_first_tick_callback_sp_each(function callback)
    Registers a function to be called when the first tick occurs in a singleplayer game, whether new or loaded from a savegame.

    Parameters:

    1

    function

    callback

    Returns:

    1. nil

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

    campaign_manager:add_first_tick_callback_mp_new(function callback)
    Registers a function to be called when the first tick occurs in a new multiplayer game.

    Parameters:

    1

    function

    callback

    Returns:

    1. nil

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

    campaign_manager:add_first_tick_callback_mp_each(function callback)
    Registers a function to be called when the first tick occurs in a multiplayer game, whether new or loaded from a savegame.

    Parameters:

    1

    function

    callback

    Returns:

    1. nil

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

    campaign_manager:add_first_tick_callback_new(function callback)
    Registers a function to be called when the first tick occurs in a new game, whether singleplayer or multiplayer.

    Parameters:

    1

    function

    callback

    Returns:

    1. nil

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

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

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

    Parameters:

    1

    object

    campaign object

    Returns:

    1. string summary of object

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

    Back to top

    Timer Callbacks

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

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

    Parameters:

    1

    function

    callback to call

    2

    number

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

    3

    string

    optional, default value=nil

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

    Returns:

    1. nil

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

    campaign_manager:repeat_callback(function callback to call, number time, [string name])
    Calls the supplied function repeatedly after the supplied period in seconds. A string name for the callback may optionally be provided to allow the callback to be cancelled. Cancelling the callback is the only method to stop a repeat callback, once started.

    Parameters:

    1

    function

    callback to call

    2

    number

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

    3

    string

    optional, default value=nil

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

    Returns:

    1. nil

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

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

    Parameters:

    1

    function

    callback to call

    2

    number

    Time in seconds after to which to call the callback.

    3

    string

    optional, default value=nil

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

    Returns:

    1. nil

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

    campaign_manager:remove_callback([string name])
    Removes all pending callbacks that matches the supplied name.

    Parameters:

    1

    string

    optional, default value=nil

    Callback name to remove.

    Returns:

    1. nil

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

    campaign_manager:dump_timers()
    Prints all timers to the console, for debug purposes.

    Returns:

    1. nil

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

    Back to top

    General Querying

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

    Returns:

    1. boolean is multiplayer campaign

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

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

    Returns:

    1. boolean is new game

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

    campaign_manager:is_game_running()
    Returns whether or not the game is loaded and time is ticking.

    Returns:

    1. boolean is game started

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

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

    Returns:

    1. object model

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

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

    Returns:

    1. object game_interface

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

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

    Parameters:

    1

    boolean

    optional, default value=false

    return as string

    Returns:

    1. object difficulty integer or string

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

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

    Parameters:

    1

    boolean

    optional, default value=false

    force result

    Returns:

    1. string local faction name

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

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

    Returns:

    1. table human factions

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

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

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

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

    Returns:

    1. string faction key

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

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

    Returns:

    1. boolean is local player's turn

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

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

    Returns:

    1. boolean battle is happening

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

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

    Returns:

    1. number turn number

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

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

    Parameters:

    1

    number

    modifier

    Returns:

    1. nil

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

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

    Returns:

    1. null_interface

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

    campaign_manager:help_page_seen(string help page name)
    Returns whether the advice history indicates that a specific help page has been viewed by the player.

    Parameters:

    1

    string

    help page name

    Returns:

    1. boolean help page viewed

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

    Back to top

    Building Queries & Modification

    campaign_manager:building_exists_in_province(string building key, string province key)
    Returns whether the supplied building exists in the supplied province.

    Parameters:

    1

    string

    building key

    2

    string

    province key

    Returns:

    1. boolean building exist

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

    Back to top

    Character Queries & Modification

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

    Parameters:

    1

    region

    region object

    Returns:

    1. character garrison commander

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

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

    Parameters:

    1

    object

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

    2

    number

    Logical x co-ordinate.

    3

    number

    Logical y co-ordinate.

    4

    boolean

    optional, default value=false

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

    Returns:

    1. character closest character

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

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

    Parameters:

    1

    object

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

    2

    number

    Logical x co-ordinate.

    3

    number

    Logical y co-ordinate.

    4

    boolean

    optional, default value=false

    Restrict search results to generals.

    5

    boolean

    optional, default value=false

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

    Returns:

    1. character closest character

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

    campaign_manager:get_general_at_position_all_factions(number x, number y)
    Returns the general character stood at the supplied position, regardless of faction. Garrison commanders are not returned.

    Parameters:

    1

    number

    Logical x co-ordinate.

    2

    number

    Logical y co-ordinate.

    Returns:

    1. character general character

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

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

    Parameters:

    1

    number

    cqi

    Returns:

    1. character character

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

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

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

    Parameters:

    1

    number

    military force cqi

    Returns:

    1. character general character

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

    campaign_manager:char_display_pos(character character)
    Returns the x/y display position of the supplied character.

    Parameters:

    1

    character

    character

    Returns:

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

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

    campaign_manager:char_logical_pos(character character)
    Returns the x/y logical position of the supplied character.

    Parameters:

    1

    character

    character

    Returns:

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

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

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

    Parameters:

    1

    character

    character

    Returns:

    1. boolean is army commander

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

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

    Parameters:

    1

    object

    character or character cqi

    Returns:

    1. string lookup string

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

    campaign_manager:char_in_owned_region(character character)
    Returns true if the supplied character is in a region their faction controls, false otherwise.

    Parameters:

    1

    character

    character

    Returns:

    1. boolean stood in owned region

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

    campaign_manager:char_has_army(character character)
    Returns true if the supplied character has a land army military force, false otherwise.

    Parameters:

    1

    character

    character

    Returns:

    1. boolean has army

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

    campaign_manager:char_has_navy(character character)
    Returns true if the supplied character has a navy military force, false otherwise.

    Parameters:

    1

    character

    character

    Returns:

    1. boolean has navy

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

    campaign_manager:char_is_agent(character character)
    Returns true if the supplied character is not a general, a colonel or a minister, false otherwise.

    Parameters:

    1

    character

    character

    Returns:

    1. boolean is agent

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

    campaign_manager:char_is_general(character character)
    Returns true if the supplied character is of type 'general', false otherwise.

    Parameters:

    1

    character

    character

    Returns:

    1. boolean is general

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

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

    Parameters:

    1

    character

    character

    Returns:

    1. boolean is victorious general

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

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

    Parameters:

    1

    character

    character

    Returns:

    1. boolean is defeated general

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

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

    Parameters:

    1

    character

    character

    Returns:

    1. boolean is general with army

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

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

    Parameters:

    1

    character

    character

    Returns:

    1. boolean is general with army

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

    campaign_manager:char_is_general_with_navy(character character)
    Returns true if the supplied character is a general with a military force that is a navy, false otherwise.

    Parameters:

    1

    character

    character

    Returns:

    1. boolean is general with navy

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

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

    Parameters:

    1

    character

    character

    Returns:

    1. boolean is governor

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

    campaign_manager:char_is_in_region_list(character character, table table of region keys)
    Returns true if the supplied character is currently in any region from a supplied list, false otherwise.

    Parameters:

    1

    character

    character

    2

    table

    table of region keys

    Returns:

    1. boolean is in region list

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

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

    Parameters:

    1

    string

    faction key

    2

    string

    subculture key

    Returns:

    1. character closest visible character

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

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

    Parameters:

    1

    faction

    faction

    2

    number

    x

    3

    number

    y

    Returns:

    1. character closest character

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

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

    Parameters:

    1

    character

    source character

    2

    character

    target character

    Returns:

    1. boolean can reach

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

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

    Parameters:

    1

    character

    source character

    2

    settlement

    target settlement

    Returns:

    1. boolean can reach

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

    campaign_manager:general_with_forename_exists_in_faction_with_force(
      string     faction key,
      string     forename key
    )
    Returns true if a general with a mobile military force exists in the supplied faction with the supplied forename. Faction and forename are specified by string key.

    Parameters:

    1

    string

    Faction key.

    2

    string

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

    Returns:

    1. boolean general exists

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

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

    Parameters:

    1

    object

    Faction, either by faction object or by string key.

    Returns:

    1. character highest ranked character

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

    campaign_manager:remove_all_units_from_general(character general character)
    Removes all units from the military force the supplied general character commands.

    Parameters:

    1

    character

    general character

    Returns:

    1. number number of units removed

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

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

    Back to top

    Faction Queries & Modification

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

    Parameters:

    1

    string

    faction key

    Returns:

    1. faction faction

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

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

    Parameters:

    1

    faction

    faction object

    2

    string

    building key

    Returns:

    1. faction contains building

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

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

    Parameters:

    1

    faction

    faction object

    2

    string

    character type

    Returns:

    1. number number of characters

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

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

    Parameters:

    1

    faction

    faction object

    Returns:

    1. number number of armies killed

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

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

    Parameters:

    1

    faction

    faction object

    Returns:

    1. table of character command queue indexes

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

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

    Parameters:

    1

    faction

    faction object

    2

    boolean

    optional, default value=false

    exclude armed citizenry

    Returns:

    1. number number of units

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

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

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

    Parameters:

    1

    faction

    faction object

    Returns:

    1. boolean faction is alive

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

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

    Parameters:

    1

    string

    culture key

    Returns:

    1. boolean any faction is alive

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

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

    Parameters:

    1

    string

    subculture key

    Returns:

    1. boolean any faction is alive

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

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

    Parameters:

    1

    faction

    faction

    Returns:

    1. boolean has armies in enemy territory

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

    campaign_manager:faction_has_armies_in_region(faction faction, region region)
    Returns true if the supplied faction has any armies in the supplied region, false otherwise.

    Parameters:

    1

    faction

    faction

    2

    region

    region

    Returns:

    1. boolean armies in region

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

    campaign_manager:faction_has_nap_with_faction(faction faction, region region)
    Returns true if the supplied faction has any armies in the supplied region, false otherwise.

    Parameters:

    1

    faction

    faction

    2

    region

    region

    Returns:

    1. boolean armies in region

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

    campaign_manager:faction_has_trade_agreement_with_faction(faction faction, region region)
    Returns true if the supplied faction has any armies in the supplied region, false otherwise.

    Parameters:

    1

    faction

    faction

    2

    region

    region

    Returns:

    1. boolean armies in region

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

    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. This is specified by PROVINCE_SCRIPT_INTERFACE - see the game interface documentation for more information.

    2

    faction

    Faction to query. This is specified by FACTION_SCRIPT_INTERFACE - see the game interface documentation for more information.

    Returns:

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

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

    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. This is specified by FACTION_SCRIPT_INTERFACE - see the game interface documentation for more information.

    Returns:

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

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

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

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

    Parameters:

    1

    faction

    FACTION_SCRIPT_INTERFACE for the subject faction.

    2

    boolean

    optional, default value=false

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

    3

    boolean

    optional, default value=false

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

    Returns:

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

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

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

    Back to top

    Garrison Residence Queries

    campaign_manager:garrison_contains_building(garrison_residence garrison residence, string building key)
    Returns true if the supplied garrison residence contains a building with the supplied key, false otherwise.

    Parameters:

    1

    garrison_residence

    garrison residence

    2

    string

    building key

    Returns:

    1. boolean garrison contains building

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

    campaign_manager:garrison_contains_building_chain(
      garrison_residence     garrison residence,
      string     building chain key
    )
    Returns true if the supplied garrison residence contains a building with the supplied chain key, false otherwise.

    Parameters:

    1

    garrison_residence

    garrison residence

    2

    string

    building chain key

    Returns:

    1. boolean garrison contains building

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

    campaign_manager:garrison_contains_building_superchain(
      garrison_residence     garrison residence,
      string     building superchain key
    )
    Returns true if the supplied garrison residence contains a building with the supplied superchain key, false otherwise.

    Parameters:

    1

    garrison_residence

    garrison residence

    2

    string

    building superchain key

    Returns:

    1. boolean garrison contains building

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

    campaign_manager:get_armed_citizenry_from_garrison(
      garrison_residence     garrison residence,
      [boolean     get naval]
    )
    Returns the garrison army from a garrison residence. By default this returns the land army armed citizenry - an optional flag instructs the function to return the naval armed citizenry instead.

    Parameters:

    1

    garrison_residence

    Garrison residence.

    2

    boolean

    optional, default value=false

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

    Returns:

    1. boolean armed citizenry army

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

    Back to top

    Military Force Queries

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

    Parameters:

    1

    number

    cqi

    Returns:

    1. military_force military force

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

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

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

    Parameters:

    1

    military_force

    military force

    Returns:

    1. number average strength percentage

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

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

    Parameters:

    1

    military_force_list

    military force list

    Returns:

    1. number number of mobile forces

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

    campaign_manager:proportion_of_unit_class_in_military_force(
      military_force     military force,
      string     unit class
    )
    Returns the unary proportion (0-1) of units in the supplied military force which are of the supplied unit class.

    Parameters:

    1

    military_force

    military force

    2

    string

    unit class

    Returns:

    1. proportion units of unit class

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

    campaign_manager:military_force_contains_unit_type_from_list(
      military_force     military force,
      table     unit type list
    )
    Returns true if the supplied military force contains any units of a type contained in the supplied unit type list, false otherwise.

    Parameters:

    1

    military_force

    Military force.

    2

    table

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

    Returns:

    1. force contains unit from type list

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

    campaign_manager:military_force_contains_unit_class_from_list(
      military_force     military force,
      table     unit class list
    )
    Returns true if the supplied military force contains any units of a class contained in the supplied unit class list, false otherwise.

    Parameters:

    1

    military_force

    Military force.

    2

    table

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

    Returns:

    1. force contains unit from class list

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

    campaign_manager:force_from_general_cqi(number general cqi)
    Returns the force whose commanding general has the passed cqi. If no force is found then false is returned.

    Parameters:

    1

    number

    general cqi

    Returns:

    1. military force force

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

    campaign_manager:force_gold_value(number force cqi)
    Returns the gold value of all of the units in the force.

    Parameters:

    1

    number

    force cqi

    Returns:

    1. number value

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

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

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

    Parameters:

    1

    string

    region name

    Returns:

    1. region region

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

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

    Parameters:

    1

    region

    subject region

    Returns:

    1. boolean region has neighbour of different religion

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

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

    campaign_manager:instantly_dismantle_building_in_region(string region key, number slot number)
    Instantly dismantles the building in the supplied slot number of the supplied region.

    Parameters:

    1

    string

    region key

    2

    number

    slot number

    Returns:

    1. nil

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

    campaign_manager:get_most_pious_region_for_faction_for_religion(
      faction     subject faction,
      string     religion key
    )
    Returns the region held by a specified faction that has the highest proportion of a specified religion. The numeric religion proportion is also returned.

    Parameters:

    1

    faction

    subject faction

    2

    string

    religion key

    Returns:

    1. region most pious region
    2. number religion proportion

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

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

    Parameters:

    1

    string

    region key

    2

    number

    storm strength

    3

    number

    duration

    4

    string

    storm type

    Returns:

    1. nil

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

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

    Back to top

    Settlement Queries

    campaign_manager:settlement_display_pos(string settlement name)
    Returns the display position of a supplied settlement by string name.

    Parameters:

    1

    string

    settlement name

    Returns:

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

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

    campaign_manager:settlement_logical_pos(string settlement name)
    Returns the logical position of a supplied settlement by string name.

    Parameters:

    1

    string

    settlement name

    Returns:

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

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

    Back to top

    Pending Battle Cache

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

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

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

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

    Returns:

    1. number number of attacking armies

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

    campaign_manager:pending_battle_cache_get_attacker(number index of attacker)
    Returns records relating to a particular attacker in the cached pending battle. The attacker is specified by numerical index, with the first being accessible at record 1. This function returns the cqi of the commanding character, the cqi of the military force, and the faction name.
    To get records of the units related to an attacker, use campaign_manager:pending_battle_cache_num_attacker_units and campaign_manager:pending_battle_cache_get_attacker_unit.

    Parameters:

    1

    number

    index of attacker

    Returns:

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

    Example - print attacker details:

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

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

    campaign_manager:pending_battle_cache_get_attacker_units(number index of attacker)
    Returns just a table containing the unit keys of a particular attacker in the cached pending battle. The attacker is specified by numerical index, with the first being accessible at record 1.

    Parameters:

    1

    number

    index of attacker

    Returns:

    1. table unit keys

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

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

    Parameters:

    1

    number

    index of attacker

    Returns:

    1. string faction name

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

    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.

    Parameters:

    1

    number

    index of attacker

    Returns:

    1. number number of attacking units

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

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

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

    Parameters:

    1

    number

    Index of attacking character within the pending battle cache.

    2

    number

    Index of unit belonging to the attacking character.

    Returns:

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

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

    campaign_manager:pending_battle_cache_num_defenders()
    Returns the number of defending armies in the cached pending battle.

    Returns:

    1. number number of defending armies

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

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

    Parameters:

    1

    number

    index of defender

    Returns:

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

    Example - print defender details:

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

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

    campaign_manager:pending_battle_cache_get_defender_units(number index of defender)
    Returns just a table containing the unit keys of a particular defender in the cached pending battle. The defender is specified by numerical index, with the first being accessible at record 1.

    Parameters:

    1

    number

    index of defender

    Returns:

    1. table unit keys

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

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

    Parameters:

    1

    number

    index of defender

    Returns:

    1. string faction name

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

    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.

    Parameters:

    1

    number

    index of defender

    Returns:

    1. number number of attacking units

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

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

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

    Parameters:

    1

    number

    Index of attacking character within the pending battle cache.

    2

    number

    Index of unit belonging to the attacking character.

    Returns:

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

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

    campaign_manager:pending_battle_cache_faction_is_attacker(string faction key)
    Returns true if the faction was an attacker (primary or reinforcing) in the cached pending battle.

    Parameters:

    1

    string

    faction key

    Returns:

    1. boolean faction was attacker

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

    campaign_manager:pending_battle_cache_faction_is_defender(string faction key)
    Returns true if the faction was a defender (primary or reinforcing) in the cached pending battle.

    Parameters:

    1

    string

    faction key

    Returns:

    1. boolean faction was defender

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

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

    Parameters:

    1

    string

    faction key

    Returns:

    1. boolean faction was involved

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

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

    Returns:

    1. boolean human was attacking

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

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

    Returns:

    1. boolean human was defending

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

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

    Returns:

    1. boolean human was involved

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

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

    Parameters:

    1

    object

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

    Returns:

    1. boolean character was attacker

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

    campaign_manager:pending_battle_cache_char_is_defender(object character)
    Returns true if the supplied character was a defender in the cached pending battle.

    Parameters:

    1

    object

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

    Returns:

    1. boolean character was defender

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

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

    Parameters:

    1

    object

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

    Returns:

    1. boolean character was involved

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

    campaign_manager:pending_battle_cache_mf_is_attacker(number cqi)
    Returns true if the supplied military force was an attacker in the cached pending battle.

    Parameters:

    1

    number

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

    Returns:

    1. boolean force was attacker

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

    campaign_manager:pending_battle_cache_mf_is_defender(number cqi)
    Returns true if the supplied military force was a defender in the cached pending battle.

    Parameters:

    1

    number

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

    Returns:

    1. boolean force was defender

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

    campaign_manager:pending_battle_cache_mf_is_involved(number cqi)
    Returns true if the supplied military force was an attacker or defender in the cached pending battle.

    Parameters:

    1

    number

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

    Returns:

    1. boolean force was involved

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

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

    Parameters:

    1

    character

    character to query

    Returns:

    1. table table of enemy characters

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

    campaign_manager:pending_battle_cache_is_quest_battle()
    Returns true if any of the participating factions in the pending battle are quest battle factions, false otherwise.

    Returns:

    1. boolean is quest battle

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

    campaign_manager:pending_battle_cache_attacker_victory()
    Returns true if the pending battle has been won by the attacker, false otherwise.

    Returns:

    1. boolean attacker has won

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

    campaign_manager:pending_battle_cache_defender_victory()
    Returns true if the pending battle has been won by the defender, false otherwise.

    Returns:

    1. boolean defender has won

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

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

    Returns:

    1. number gold value of attacking forces

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

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

    Returns:

    1. number gold value of defending forces

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

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

    Parameters:

    1

    string

    unit key

    Returns:

    1. boolean unit was involved as attacker

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

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

    Parameters:

    1

    string

    unit key

    Returns:

    1. boolean unit was involved as defender

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

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

    Parameters:

    1

    string

    unit key

    Returns:

    1. boolean unit was involved

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

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

    campaign_manager:random_sort_copy(table numerically-indexed table)

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

    Parameters:

    1

    table

    Numerically-indexed table.

    Returns:

    1. table randomly-sorted table

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

    Back to top

    Campaign UI

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

    Returns:

    1. campaign_ui_manager

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

    campaign_manager:highlight_event_dismiss_button([boolean should highlight])
    Activates or deactivates a highlight on the event panel dismiss button. This may not work in all circumstances.

    Parameters:

    1

    boolean

    optional, default value=true

    should highlight

    Returns:

    1. nil

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

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

    Returns:

    1. nil

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

    campaign_manager:enable_ui_hiding([boolean enable hiding])
    Enables or disables the ability of the player to hide the UI.

    Parameters:

    1

    boolean

    optional, default value=true

    enable hiding

    Returns:

    1. nil

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

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

    campaign_manager:disable_all_shortcuts(bool disabled)
    Disables/Enables ALL shortcuts in the underlaying SHORTCUT_HANDLER. This is a wrapper of a c++ function with the same name.

    Parameters:

    1

    bool

    true for disable, false for enable.

    Returns:

    1. nil

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

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

    Returns:

    1. boolean is ui hiding enabled

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

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

    campaign_manager:scroll_camera_from_current(boolean correct endpoint, number time, ... positions)
    Scrolls the camera from the current camera position. This is the same as callling campaign_manager:scroll_camera_with_direction with the current camera position as the first set of co-ordinates.

    Parameters:

    1

    boolean

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

    2

    number

    Time in seconds over which to scroll.

    3

    ...

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

    Returns:

    1. nil

    Example:

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

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

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

    Parameters:

    1

    number

    Time in seconds over which to scroll.

    2

    function

    optional, default value=nil

    Optional callback to call when the cutscene ends.

    3

    ...

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

    Returns:

    1. nil

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

    campaign_manager:cut_and_scroll_camera_with_cutscene(
      number     time,
      [function     callback],
      ...     positions. One or more camera positions must be supplied. Each position should be a table with five number components
    )
    Scrolls the camera through the supplied list of camera points in a cutscene. Cinematic borders will be shown (unless disabled with campaign_manager:set_use_cinematic_borders_for_automated_cutscenes), the UI hidden, and interaction with the game disabled while the camera is scrolling. The player will be able to skip the cutscene with the ESC key, in which case the camera will jump to the end position.

    Parameters:

    1

    number

    Time in seconds over which to scroll.

    2

    function

    optional, default value=nil

    Optional callback to call when the cutscene ends.

    3

    ...

    as described in the description of the Camera Movement section.

    Returns:

    1. nil

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

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

    Parameters:

    1

    number

    Time in seconds over which to scroll.

    2

    function

    optional, default value=nil

    Optional callback to call when the cutscene ends.

    3

    string

    Key of region containing target settlement.

    Returns:

    1. nil

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

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

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

    Parameters:

    1

    number

    Time in seconds over which to scroll.

    2

    function

    optional, default value=nil

    Optional callback to call when the cutscene ends.

    3

    number

    CQI of target character.

    Returns:

    1. nil

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

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

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

    Parameters:

    1

    boolean

    optional, default value=true

    show borders

    Returns:

    1. nil

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

    campaign_manager:position_camera_at_primary_military_force(string faction key)
    Immediately positions the camera at a position looking at the primary military force for the supplied faction. The faction is specified by key.

    Parameters:

    1

    string

    faction key

    Returns:

    1. nil

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

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

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

    Parameters:

    1

    string

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

    2

    number

    optional, default value=nil

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

    3

    number

    optional, default value=nil

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

    Returns:

    1. nil

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

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

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

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

    Parameters:

    1

    string

    optional, default value="default"

    cache name

    Returns:

    1. nil

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

    campaign_manager:cached_camera_position_exists([string cache name])
    Returns whether a camera position is currently cached for the (optional) supplied cache name.

    Parameters:

    1

    string

    optional, default value="default"

    cache name

    Returns:

    1. boolean camera position is cached

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

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

    Parameters:

    1

    string

    optional, default value="default"

    cache name

    Returns:

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

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

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

    Parameters:

    1

    string

    optional, default value="default"

    cache name

    Returns:

    1. nil

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

    campaign_manager:delete_cached_camera_position([string cache name])
    Removes the cache for the supplied cache name. If no cache name is specified the default cache (cache name "default") is deleted.

    Parameters:

    1

    string

    optional, default value="default"

    cache name

    Returns:

    1. nil

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

    Back to top

    Cutscenes and Key Stealing

    campaign_manager:show_subtitle(string text key, [boolean full text key supplied], [boolean force diplay])
    Shows subtitled text during a cutscene. The text is displayed until campaign_manager:hide_subtitles is called.

    Parameters:

    1

    string

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

    2

    boolean

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

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

    3

    boolean

    optional, default value=false

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

    Returns:

    1. nil

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

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

    Returns:

    1. nil

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

    campaign_manager:is_any_cutscene_running()
    Returns true if any campaign_cutscene is running, false otherwise.

    Returns:

    1. boolean is any cutscene running

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

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

    Returns:

    1. nil

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

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

    Parameters:

    1

    boolean

    steal

    Returns:

    1. nil

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

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

    Parameters:

    1

    boolean

    steal

    Returns:

    1. nil

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

    campaign_manager:on_key_press_up(string key pressed)
    Called by the campaign model when a key stolen by steal_user_input or steal_escape_key is pressed. Client scripts should not call this!

    Parameters:

    1

    string

    key pressed

    Returns:

    1. nil

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

    campaign_manager:print_key_steal_entries()
    Debug output of all current stolen key records.

    Returns:

    1. nil

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

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

    Parameters:

    1

    string

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

    2

    string

    Key name.

    3

    function

    Function to call when the key is pressed.

    Returns:

    1. nil

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

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

    Parameters:

    1

    string

    Unique name for this key-steal entry.

    2

    string

    Key name.

    Returns:

    1. nil

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

    campaign_manager:steal_escape_key_with_callback(string name, function callback)
    Steals the escape key and registers a function to call when it is pressed. Unlike campaign_manager:steal_key_with_callback this automatically calls campaign_manager:steal_escape_key if the key is not already stolen.

    Parameters:

    1

    string

    Unique name for this key-steal entry.

    2

    function

    Function to call when the key is pressed.

    Returns:

    1. nil

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

    campaign_manager:release_escape_key_with_callback(string name)
    Releases the escape key after it's been stolen with campaign_manager:steal_escape_key_with_callback.

    Parameters:

    1

    string

    Unique name for this key-steal entry.

    Returns:

    1. nil

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

    campaign_manager:steal_escape_key_and_space_bar_with_callback(string name, function callback)
    Steals the escape key and spacebar and registers a function to call when they are pressed.

    Parameters:

    1

    string

    Unique name for this key-steal entry.

    2

    function

    Function to call when one of the keys are pressed.

    Returns:

    1. nil

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

    campaign_manager:release_escape_key_and_space_bar_with_callback(string name, function callback)
    Releases the escape key and spacebar after they've been stolen with campaign_manager:steal_escape_key_and_space_bar_with_callback.

    Parameters:

    1

    string

    Unique name for this key-steal entry

    2

    function

    Function to call when one of the keys are pressed.

    Returns:

    1. nil

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

    Back to top

    Advice

    campaign_manager:show_advice(
      string     advice key,
      [boolean     show progress button],
      [boolean     highlight progress button],
      [function     callback],
      [number     playtime],
      [number     delay]
    )
    Displays some advice. The advice to display is specified by advice_thread key.

    Parameters:

    1

    string

    Advice thread key.

    2

    boolean

    optional, default value=false

    Show progress/close button on the advisor panel.

    3

    boolean

    optional, default value=false

    Highlight the progress/close button on the advisor panel.

    4

    function

    optional, default value=nil

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

    5

    number

    optional, default value=0

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

    6

    number

    optional, default value=0

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

    Returns:

    1. nil

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

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

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

    campaign_manager:set_advice_enabled([boolean enable advice])
    Enables or disables the advice system.

    Parameters:

    1

    boolean

    optional, default value=true

    enable advice

    Returns:

    1. nil

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

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

    Returns:

    1. boolean advice is enabled

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

    campaign_manager:modify_advice([boolean show progress button], [boolean highlight progress button])
    Immediately enables or disables the close button that appears on the advisor panel, or causes it to be highlighted.

    Parameters:

    1

    boolean

    optional, default value=false

    show progress button

    2

    boolean

    optional, default value=false

    highlight progress button

    Returns:

    1. nil

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

    campaign_manager:add_pre_dismiss_advice_callback(function callback)
    Registers a callback to be called when/immediately before the advice gets dismissed.

    Parameters:

    1

    function

    callback

    Returns:

    1. nil

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

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

    Returns:

    1. nil

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

    campaign_manager:progress_on_advice_dismissed(
      function     callback,
      [number     delay],
      [boolean     highlight on finish]
    )
    Registers a function to be called when the advisor is dismissed. Only one such function can be registered at a time.

    Parameters:

    1

    function

    Callback to call.

    2

    number

    optional, default value=0

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

    3

    boolean

    optional, default value=false

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

    Returns:

    1. nil

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

    campaign_manager:cancel_progress_on_advice_dismissed()
    Cancels any running campaign_manager:progress_on_advice_dismissed process.

    Returns:

    1. nil

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

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

    Parameters:

    1

    function

    Callback to call.

    2

    number

    optional, default value=0

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

    3

    number

    optional, default value=nil

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

    4

    boolean

    optional, default value=false

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

    Returns:

    1. nil

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

    campaign_manager:cancel_progress_on_advice_finished()
    Cancels any running campaign_manager:progress_on_advice_finished process.

    Returns:

    1. nil

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

    Back to top

    Progress on UI Event

    campaign_manager:progress_on_panel_dismissed(
      string     unique name,
      string     panel name,
      function     callback,
      [number     callback delay]
    )
    Calls a supplied callback when a panel with the supplied name is closed.

    Parameters:

    1

    string

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

    2

    string

    Name of the panel.

    3

    function

    Callback to call.

    4

    number

    optional, default value=0

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

    Returns:

    1. nil

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

    campaign_manager:cancel_progress_on_panel_dismissed(string unique name)
    Cancels a monitor started with campaign_manager:progress_on_panel_dismissed by name.

    Parameters:

    1

    string

    Unique descriptive string name for this process.

    Returns:

    1. nil

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

    campaign_manager:progress_on_events_dismissed(string unique name, function callback, [number callback delay])
    Calls a supplied callback when all events panels are closed. Analagous to calling campaign_manager:progress_on_panel_dismissed with the panel name "events".

    Parameters:

    1

    string

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

    2

    function

    Callback to call.

    3

    number

    optional, default value=0

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

    Returns:

    1. nil

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

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

    Parameters:

    1

    string

    Unique descriptive string name for this process.

    Returns:

    1. nil

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

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

    Parameters:

    1

    function

    Callback to call.

    2

    number

    optional, default value=0

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

    Returns:

    1. nil

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

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

    Parameters:

    1

    function

    Callback to call.

    2

    number

    optional, default value=0

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

    Returns:

    1. nil

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

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

    Parameters:

    1

    function

    Callback to call.

    2

    number

    optional, default value=0

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

    Returns:

    1. nil

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

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

    Parameters:

    1

    string

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

    2

    function

    Callback to call.

    3

    number

    optional, default value=0

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

    Returns:

    1. nil

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

    campaign_manager:cancel_progress_on_battle_completed(string name)
    Cancels a running monitor started with campaign_manager:progress_on_battle_completed by name.

    Parameters:

    1

    string

    Name of monitor to cancel.

    Returns:

    1. nil

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

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

    Parameters:

    1

    function

    Callback to call.

    2

    number

    optional, default value=0

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

    Returns:

    1. nil

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

    campaign_manager:cancel_progress_on_camera_movement_finished()
    Cancels a running monitor started with campaign_manager:progress_on_camera_movement_finished.

    Returns:

    1. nil

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

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

    Parameters:

    1

    function

    Callback to call.

    2

    number

    optional, default value=0

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

    Returns:

    1. nil

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

    campaign_manager:cancel_progress_on_post_battle_panel_visible()
    Cancels a running monitor started with campaign_manager:progress_on_post_battle_panel_visible.

    Returns:

    1. nil

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

    Back to top

    Character Creation and Manipulation

    campaign_manager:create_force(
      string     faction key,
      string     unit list,
      string     region key,
      number     x,
      number     y,
      boolean     exclude named characters,
      [function     success callback]
    )
    Wrapper for create_force function on the underlying game interface, which instantly spawns an army with a general on the campaign map. This wrapper function adds debug output and success callback functionality.
    Note that the underlying create_force function supports the call not going through the command queue, but this wrapper forces it to do so as doing otherwise seems to break in multiplayer.

    Parameters:

    1

    string

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

    2

    string

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

    3

    string

    Region key of home region for this force.

    4

    number

    x logical co-ordinate of force.

    5

    number

    y logical co-ordinate of force.

    6

    boolean

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

    7

    function

    optional, default value=nil

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

    Returns:

    1. nil

    Example:

    cm:create_force(
        "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 ../working_data/script/_lib/lib_campaign_manager.lua, line 7518

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

    Parameters:

    1

    string

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

    2

    string

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

    3

    string

    Region key of home region for this force.

    4

    number

    x logical co-ordinate of force.

    5

    number

    y logical co-ordinate of force.

    6

    string

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

    7

    string

    Character subtype of character at the head of the army.

    8

    string

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

    9

    string

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

    10

    string

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

    11

    string

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

    12

    boolean

    Make the spawned character the faction leader.

    13

    function

    optional, default value=nil

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

    Returns:

    1. nil

    Example:

    cm:create_force_with_general(
        "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 ../working_data/script/_lib/lib_campaign_manager.lua, line 7620

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

    Parameters:

    1

    string

    Character lookup string for the general character.

    2

    string

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

    3

    string

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

    4

    string

    Region key of home region for this force.

    5

    number

    x logical co-ordinate of force.

    6

    number

    y logical co-ordinate of force.

    7

    function

    optional, default value=nil

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

    Returns:

    1. nil

    Example:

    cm:create_force_with_existing_general(
        cm:char_lookup_str(char_dwf_faction_leader),
        "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 ../working_data/script/_lib/lib_campaign_manager.lua, line 7777

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

    Kills the specified character, with the ability to also destroy their whole force if they are commanding one. 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.

    3

    boolean

    optional, default value=true

    Send the create command through the command queue.

    Returns:

    1. nil

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

    campaign_manager:add_building_to_force(number military force cqi, object building(s))
    Adds one or more buildings to a horde army. The army is specified by the command queue index of the military force. A single building may be specified by a string key, or multiple buildings in a table.

    Parameters:

    1

    number

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

    2

    object

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

    Returns:

    1. nil

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

    campaign_manager:create_agent(
      string     faction key,
      string     character type,
      string     character subtype,
      number     x,
      number     y,
      string     id,
      boolean     use command queue,
      [function     success callback]
    )
    Wrapper for create_agent function on the underlying game interface which adds input validation and 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

    boolean

    Send the create command through the command queue.

    8

    function

    optional, default value=nil

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

    Returns:

    1. nil

    Example:

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

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

    campaign_manager:respawn_convalescing_agent(
      string     faction key,
      number     x,
      number     y,
      string     character_lookup_string,
      [function     success callback]
    )
    Wrapper for respawn_convalescing_agent function on the underlying game interface which adds input validation and console output. 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

    lookup string using cm:char_lookup_str()

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

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

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

    campaign_manager:move_character(
      number     cqi,
      number     x,
      number     y,
      [boolean     should replenish],
      [boolean     allow post movement],
      [function     success callback],
      [function     fail callback]
    )
    Helper function to move a character.

    Parameters:

    1

    number

    Command-queue-index of the character to move.

    2

    number

    x co-ordinate of the intended destination.

    3

    number

    y co-ordinate of the intended destination.

    4

    boolean

    optional, default value=false

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

    5

    boolean

    optional, default value=true

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

    6

    function

    optional, default value=nil

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

    7

    function

    optional, default value=nil

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

    Returns:

    1. nil

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

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

    Returns:

    1. nil

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

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

    Parameters:

    1

    number

    Command-queue-index of the subject character.

    2

    function

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

    3

    function

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

    Returns:

    1. nil

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

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

    Parameters:

    1

    number

    Command-queue-index of the subject character.

    Returns:

    1. nil

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

    campaign_manager:notify_on_character_halt(number cqi, function callback, [boolean must move first])
    Calls the supplied callback as soon as a character is determined to be stationary. This uses campaign_manager:is_character_moving to determine if the character moving so the callback will not be called the instant the character halts.

    Parameters:

    1

    number

    Command-queue-index of the subject character.

    2

    function

    Callback to call.

    3

    boolean

    optional, default value=false

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

    Returns:

    1. nil

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

    campaign_manager:stop_notify_on_character_halt(number cqi)
    Stops any monitor started by campaign_manager:notify_on_character_halt, by character cqi.

    Parameters:

    1

    number

    Command-queue-index of the subject character.

    Returns:

    1. nil

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

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

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

    campaign_manager:attack(string attacker, string defender, boolean command queue)
    Instruct a character at the head of a military force to attack another. This function is a wrapper for attack function on the underlying game interface, which also enables movement for the character and prints output to console.

    Parameters:

    1

    string

    Attacker character string, uses standard character lookup string system.

    2

    string

    Defender character string, uses standard character lookup string system.

    3

    boolean

    Order goes via command queue.

    Returns:

    1. nil

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

    campaign_manager:teleport_to(string character string, number x, number y, [boolean command queue])
    Teleports a character to a logical position on the campaign map. This is a validation/output wrapper for a function of the same name on the underlying game interface.
    This function can also reposition the camera, so it's best used on game creation to move characters around at the start of the campaign, rather than on the first tick or later.

    Parameters:

    1

    string

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

    2

    number

    Logical x co-ordinate to teleport to.

    3

    number

    Logical y co-ordinate to teleport to.

    4

    boolean

    optional, default value=false

    Order goes via command queue.

    Returns:

    1. nil

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

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

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

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

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

    Parameters:

    1

    string

    char lookup string

    Returns:

    1. nil

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

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

    Parameters:

    1

    string

    char lookup string

    Returns:

    1. nil

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

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

    Parameters:

    1

    string

    faction key

    Returns:

    1. nil

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

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

    Parameters:

    1

    string

    faction key

    Returns:

    1. nil

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

    campaign_manager:force_add_ancillary(string character string, string ancillary key)
    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.

    Returns:

    1. nil

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

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

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

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

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

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

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

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

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

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

    Parameters:

    1

    number

    x co-ordinate of the first position.

    2

    number

    y co-ordinate of the first position.

    3

    number

    x co-ordinate of the second position.

    4

    number

    y co-ordinate of the second position.

    Returns:

    1. number distance between positions squared.

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

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

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

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

    Back to top

    Restricting Units, Buildings, and Technologies

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

    campaign_manager:restrict_units_for_faction(string faction name, table unit list, [boolean should restrict])
    Applies a restriction to or removes a restriction from a faction recruiting one or more unit types.

    Parameters:

    1

    string

    Faction name.

    2

    table

    Numerically-indexed table of string unit keys.

    3

    boolean

    optional, default value=true

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

    Returns:

    1. nil

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

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

    Parameters:

    1

    string

    Faction name.

    2

    table

    Numerically-indexed table of string building keys.

    3

    boolean

    optional, default value=true

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

    Returns:

    1. nil

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

    campaign_manager:restrict_technologies_for_faction(
      string     faction name,
      table     building list,
      [boolean     should restrict]
    )
    Restricts or unrestricts a faction from researching one or more technologies.

    Parameters:

    1

    string

    Faction name.

    2

    table

    Numerically-indexed table of string technology keys.

    3

    boolean

    optional, default value=true

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

    Returns:

    1. nil

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

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

    campaign_manager:remove_effect_bundle(string effect bundle key, string faction key)
    Removes an effect bundle from a faction.

    Parameters:

    1

    string

    Effect bundle key from the effect bundles table.

    2

    string

    Faction key of the faction to remove the effect from.

    Returns:

    1. nil

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

    campaign_manager:apply_effect_bundle_to_force(string effect bundle key, string number cqi, number turns)
    Applies an effect bundle to a military force by cqi for a number of turns (can be infinite).

    Parameters:

    1

    string

    Effect bundle key from the effect bundles table.

    2

    string

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

    3

    number

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

    Returns:

    1. nil

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

    campaign_manager:remove_effect_bundle_from_force(string effect bundle key, string number cqi)
    Removes an effect bundle from a military force by cqi.

    Parameters:

    1

    string

    Effect bundle key from the effect bundles table.

    2

    string

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

    Returns:

    1. nil

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

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

    Parameters:

    1

    string

    Effect bundle key from the effect bundles table.

    2

    string

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

    3

    number

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

    Returns:

    1. nil

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

    campaign_manager:remove_effect_bundle_from_characters_force(string effect bundle key, string number cqi)
    Removes an effect bundle from a military force by its commanding character's cqi.

    Parameters:

    1

    string

    Effect bundle key from the effect bundles table.

    2

    string

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

    Returns:

    1. nil

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

    campaign_manager:apply_effect_bundle_to_region(string effect bundle key, string region key, number turns)
    Applies an effect bundle to a region for a number of turns (can be infinite).

    Parameters:

    1

    string

    Effect bundle key from the effect bundles table.

    2

    string

    Key of the region to add the effect bundle to.

    3

    number

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

    Returns:

    1. nil

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

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

    Parameters:

    1

    string

    Effect bundle key from the effect bundles table.

    2

    string

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

    Returns:

    1. nil

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

    Back to top

    Shroud Manipulation

    campaign_manager:lift_all_shroud()
    Lifts the shroud on all regions. This may be useful for cutscenes in general and benchmarks in-particular.

    Returns:

    1. nil

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

    campaign_manager:make_regions_visible_in_shroud(region_keys array of strings)
    Lifts the shroud on specific regions.

    Parameters:

    1

    region_keys

    each string represents region key from the regions table

    Returns:

    1. nil

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

    campaign_manager:take_shroud_snapshot(
      save_snapshot     a boolean indicating whether the snapshot should be saved. Use this only if it is truly necessary
    )
    Take snapshot of current shroud

    Parameters:

    1

    save_snapshot

    such as entering battle or allowing a save to happen between taking the snapshot and restoring the shroud.

    Returns:

    1. nil

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

    Back to top

    Diplomacy

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

    • "trade agreement"

    • "hard military access"

    • "cancel hard military access"

    • "military alliance"

    • "regions"

    • "technology"

    • "state gift"

    • "payments"

    • "vassal"

    • "peace"

    • "war"

    • "join war"

    • "break trade"

    • "break alliance"

    • "hostages"

    • "marriage"

    • "non aggression pact"

    • "soft military access"

    • "cancel soft military access"

    • "defensive alliance"

    • "client state"

    • "form confederation"

    • "break non aggression pact"

    • "break soft military access"

    • "break defensive alliance"

    • "break vassal"

    • "break client state"

    • "state gift unilateral"

    • "diplomatic gift"

    • "single barter"

    • "barter agreements"

    • "cancel barters"

    • "cancel barters"

    • "all"

    campaign_manager:force_diplomacy(
      string     source,
      string     target,
      string     type,
      boolean     can offer,
      boolean     can accept,
      [both     directions],
      [do     not enable payments]
    )
    Restricts or unrestricts certain types of diplomacy between factions or groups of factions. Groups of factions may be specified with the strings "all", "faction:faction_key", "subculture:subculture_key" or "culture:culture_key". A source and target faction/group of factions must be specified.
    Note that the game interface function that this function calls is force_diplomacy_new, not force_diplomacy.

    Parameters:

    1

    string

    Source faction/factions identifier.

    2

    string

    Target faction/factions identifier.

    3

    string

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

    4

    boolean

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

    5

    boolean

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

    6

    both

    optional, default value=false

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

    7

    do

    optional, default value=false

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

    Returns:

    1. nil

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

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

    campaign_manager:enable_all_diplomacy(boolean enable diplomacy)
    Enables or disables all diplomatic options between all factions.

    Parameters:

    1

    boolean

    enable diplomacy

    Returns:

    1. nil

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

    campaign_manager:force_declare_war(
      string     faction key,
      string     faction key,
      boolean     invite faction a allies,
      boolean     invite faction b allies,
      boolean     command queue or not
    )
    Forces war between two factions. This calls the function of the same name on the game interface, but adds validation and output. This output will be shown 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

    command queue or not

    Returns:

    1. nil

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

    Back to top

    Objectives and Infotext

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

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

    Parameters:

    1

    string

    Objective key, from the scripted_objectives table.

    2

    number

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

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

    3

    number

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

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

    Returns:

    1. nil

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

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

    Parameters:

    1

    string

    Objective key, from the scripted_objectives table.

    Returns:

    1. nil

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

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

    Parameters:

    1

    string

    Objective key, from the scripted_objectives table.

    Returns:

    1. nil

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

    campaign_manager:remove_objective(string objective key)
    Pass-through function for objectives_manager:remove_objective on the objectives manager. Removes a scripted objective from the scripted objectives panel.

    Parameters:

    1

    string

    Objective key, from the scripted_objectives table.

    Returns:

    1. nil

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

    campaign_manager:activate_objective_chain(
      string     chain name,
      string     objective key,
      [number     number param a],
      [number     number param b]
    )
    Pass-through function for objectives_manager:activate_objective_chain. Starts a new objective chain - see the documentation on the objectives_manager page for more details.

    Parameters:

    1

    string

    Objective chain name.

    2

    string

    Key of initial objective, from the scripted_objectives table.

    3

    number

    optional, default value=nil

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

    4

    number

    optional, default value=nil

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

    Returns:

    1. nil

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

    campaign_manager:update_objective_chain(
      string     chain name,
      string     objective key,
      [number     number param a],
      [number     number param b]
    )
    Pass-through function for objectives_manager:update_objective_chain. Updates an existing objective chain - see the documentation on the objectives_manager page for more details.

    Parameters:

    1

    string

    Objective chain name.

    2

    string

    Key of initial objective, from the scripted_objectives table.

    3

    number

    optional, default value=nil

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

    4

    number

    optional, default value=nil

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

    Returns:

    1. nil

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

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

    Parameters:

    1

    string

    Objective chain name.

    Returns:

    1. nil

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

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

    Parameters:

    1

    string

    Objective chain name.

    Returns:

    1. nil

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

    campaign_manager:add_infotext(object first param, ... additional infotext strings)
    Pass-through function for infotext_manager:add_infotext. Adds one or more lines of infotext to the infotext panel - see the documentation on the infotext_manager page for more details.

    Parameters:

    1

    object

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

    2

    ...

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

    Returns:

    1. nil

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

    campaign_manager:remove_infotext(string infotext key)
    Pass-through function for infotext_manager:remove_infotext. Removes a line of infotext from the infotext panel.

    Parameters:

    1

    string

    infotext key

    Returns:

    1. nil

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

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

    Returns:

    1. nil

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

    Back to top

    Missions and Events

    campaign_manager:cancel_mission(
      string     faction key,
      string     mission key,
      boolean     use_command_queue,
      boolean     is_custom_mission
    )
    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.

    3

    boolean

    Cancels the mission via the command queue or not.

    4

    boolean

    Is this a custom (scripted/lua generated) mission

    Returns:

    1. nil

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

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

    Triggers a specific custom mission from its database record key. This mission must be defined in the missions.txt file that accompanies each campaign. This function wraps the cm:trigger_custom_mission function on the game interface, adding 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

    Trigger the mission via the command queue or not.

    4

    boolean

    optional, default value=false

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

    5

    boolean

    optional, default value=false

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

    Returns:

    1. nil

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

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

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

    Parameters:

    1

    string

    faction key

    2

    string

    Mission definition string.

    3

    boolean

    optional, default value=false

    Trigger the mission via the command queue or not.

    4

    boolean

    optional, default value=false

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

    Returns:

    1. nil

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

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

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

    Trigger the mission via the command queue or not.

    5

    boolean

    optional, default value=false

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

    Returns:

    1. boolean mission triggered successfully

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

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

    campaign_manager:ccq_trigger_dilemma(string faction key, string dilemma key, [boolean whitelist])
    Compels the campaign director to trigger a (multiplayer safe; can be triggered from ui scripts) dilemma of a particular type, 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

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

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

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

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

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

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

    Parameters:

    1

    number

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

    2

    string

    Dilemma key, from the dilemmas table.

    3

    number

    optional, default value=0

    Command-queue index of a target faction.

    4

    number

    optional, default value=0

    Command-queue index of a second target faction.

    5

    number

    optional, default value=0

    Command-queue index of a target character.

    6

    number

    optional, default value=0

    Command-queue index of a target military force.

    7

    number

    optional, default value=0

    Command-queue index of a target region.

    8

    number

    optional, default value=0

    Command-queue index of a target settlement.

    9

    function

    Callback to call when the intervention actually gets triggered.

    Returns:

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

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

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

    Directly triggers a dilemma with a specified key and one or more target game objects. This function is a raw wrapper for the cm:trigger_dilemma_with_targets function on the game interface, adding 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

    function

    Callback to call when the intervention actually gets triggered.

    Returns:

    1. boolean Dilemma triggered successfully.

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

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

    campaign_manager:suppress_all_event_feed_messages([boolean activate suppression])
    Suppresses or unsuppresses all event feed message from being displayed. With this suppression in place, event panels won't be shown on the UI at all but will be queued and then shown when the suppression is removed. The suppression must not be kept on during the end-turn sequence.
    When suppressing, we whitelist dilemmas as they lock the model, and also mission succeeded event types as the game tends to flow better this way.

    Parameters:

    1

    boolean

    optional, default value=true

    activate suppression

    Returns:

    1. nil

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

    campaign_manager:whitelist_event_feed_event_type(string event type)
    While suppression has been activated with campaign_manager:suppress_all_event_feed_messages an event type may be whitelisted and allowed to be shown with this function. This allows scripts to hold all event messages from being displayed except those of a certain type. This is useful for advice scripts which may want to talk about those messages, for example.
    If event feed suppression is not active then calling this function will have no effect.

    Parameters:

    1

    string

    Event type to whitelist. This is compound key from the event_feed_targeted_events table, which is the event field and the target field of a record from this table, concatenated together.

    Returns:

    1. nil

    Example - Whitelisting the "enemy general dies" event type:

    cm:whitelist_event_feed_event_type("character_dies_battleevent_feed_target_opponent")

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

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

    Parameters:

    1

    boolean

    Should disable event type(s).

    2

    string

    optional, default value=""

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

    3

    string

    optional, default value=""

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

    4

    string

    optional, default value=""

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

    Returns:

    1. nil

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

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

    Constructs and displays an event. This wraps a the cm:show_message_event function of the same name on the underlying cm, 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.

    Returns:

    1. nil

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

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

    Parameters:

    1

    string

    Faction key to who the event is targeted.

    2

    string

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

    3

    string

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

    4

    string

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

    5

    number

    Logical x co-ordinate of event target.

    6

    number

    Logical y co-ordinate of event target.

    7

    boolean

    Sets this event to be persistent instead of transient.

    8

    number

    Index indicating the type of event.

    9

    function

    optional, default value=false

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

    10

    number

    optional, default value=0

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

    Returns:

    1. nil

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

    Back to top

    Transient Interventions

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

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

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

    Parameters:

    1

    string

    Name for intervention. This should be unique amongst interventions.

    2

    function

    Trigger callback to call.

    3

    boolean

    optional, default value=true

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

    4

    function

    optional, default value=nil

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

    Returns:

    1. nil

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

    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],
      [string     trigger event]
    )

    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.

    5

    string

    optional, default value=nil

    Trigger event. If this is specified, the turn countdown event won't be added until the trigger event is recev

    Returns:

    1. nil

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

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

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

    Back to top

    Pre and Post-Battle Events

    In single-player mode the campaign manager automatically monitors battles involving the player starting and finishing, and fires events at certain key times during a battle sequence that client scripts can listen for.

    The campaign manager fires the following pre-battle events:

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

        

    It also fires the following events post-battle:

    Back to top

    Values Passed to Battle

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

    EventTrigger Condition
    ScriptEventPlayerWinsBattleThe post-battle panel has opened and the player has won.
    ScriptEventPlayerWinsFieldBattleThe post-battle panel has opened and the player won a field battle (including a battle where a settlement defender sallied against them).
    ScriptEventPlayerWinsSettlementDefenceBattleThe post-battle panel has opened and the player won a settlement defence battle as the defender (including a battle where the player sallied).
    ScriptEventPlayerLosesSettlementDefenceBattleThe post-battle panel has opened and the player lost a settlement defence battle as the defender.
    ScriptEventPlayerWinsSettlementAttackBattleThe post-battle panel has opened and the player won a settlement defence battle as the attacker.
    ScriptEventPlayerLosesFieldBattleThe post-battle panel has opened and the player has lost a field battle.
    ScriptEventPlayerFoughtBattleSequenceCompletedThis event is triggered after a battle sequence in which the player fought a battle has been completed, and the camera has returned to its normal completion.
    ScriptEventPlayerBattleSequenceCompletedThis event is triggered after a battle sequence has been completed and the camera has returned to its normal completion, whether an actual battle was fought or not. This would get triggered and not ScriptEventPlayerFoughtBattleSequenceCompleted if the player were maintaining siege or retreating, for example.
    Variable NameData TypeDescription
    battle_typestringThe string battle type.
    primary_attacker_faction_namestringThe faction key of the primary attacking army.
    primary_attacker_subculturestringThe subculture key of the primary attacking army.
    primary_defender_faction_namestringThe faction key of the primary defending army.
    primary_defender_subculturestringThe subculture key of the primary defending army.
    primary_attacker_is_playerbooleanWhether the local player is the primary attacker.
    primary_defender_is_playerbooleanWhether the local player is the primary defender.

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

    Back to top

    Region Change Monitor

    When started, a region change monitor stores a record of what regions a faction holds when their turn ends and compares it to the regions the same faction holds when their next turn starts. If the two don't match, then the faction has gained or lost a region and this system fires some custom script events accordingly to notify other script.

    If the monitored faction has lost a region, the event ScriptEventFactionLostRegion will be triggered at the start of that faction's turn, with the region lost attached to the context. Should the faction have gained a region during the end-turn sequence, the event ScriptEventFactionGainedRegion will be triggered, with the region gained attached to the context.

    Region change monitors are disabled by default, and have to be opted-into by client scripts with campaign_manager:start_faction_region_change_monitor each time the scripts load.

    campaign_manager:start_faction_region_change_monitor(string faction key)
    Starts a region change monitor for a faction.

    Parameters:

    1

    string

    faction key

    Returns:

    1. nil

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

    campaign_manager:stop_faction_region_change_monitor(string faction key)
    Stops a running region change monitor for a faction.

    Parameters:

    1

    string

    faction key

    Returns:

    1. nil

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

    Back to top

    Miscellaneous Monitors

    campaign_manager:find_lowest_public_order_region_on_turn_start(string faction key)
    Starts a monitor for a faction which, on turn start for that faction, triggers a event with the faction and the region they control with the lowest public order attached. This is useful for advice scripts that may wish to know where the biggest public order problems for a faction are. This function will need to be called by client scripts each time the script starts.
    The event triggered is ScriptEventFactionTurnStartLowestPublicOrder, and the faction and region may be returned by calling faction() and region() on the context object supplied with it.

    Parameters:

    1

    string

    faction key

    Returns:

    1. nil

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

    campaign_manager:generate_region_rebels_event_for_faction(string faction key)
    RegionRebels events are sent as a faction ends their turn but before the FactionTurnEnd event is received. If called, this function listens for RegionRebels events for the specified faction, then waits for the FactionTurnEnd event to be received and sends a separate event. This flow of events works better for advice scripts.
    The event triggered is ScriptEventRegionRebels, and the faction and region may be returned by calling faction() and region() on the context object supplied with it.

    Parameters:

    1

    string

    faction key

    Returns:

    1. nil

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

    campaign_manager:start_hero_action_listener(string faction key)
    This fuction starts a listener for hero actions committed against a specified faction and sends out further events based on the outcome of those actions. It is of most use for listening for hero actions committed against a player faction.
    This function called each time the script starts for the monitors to continue running. Once started, the function triggers the following events:
    Event NameContext FunctionsDescription
    ScriptEventAgentActionSuccessAgainstCharactercharacter
    target_character    		A foreign agent (character) committed a successful action against a character (target_character) of the subject faction.
    ScriptEventAgentActionFailureAgainstCharactercharacter
    target_character    		A foreign agent (character) failed when attempting an action against a character (target_character) of the subject faction.
    ScriptEventAgentActionSuccessAgainstCharactercharacter
    garrison_residence    		A foreign agent (character) committed a successful action against a garrison residence (garrison_residence) of the subject faction.
    ScriptEventAgentActionFailureAgainstCharactercharacter
    garrison_residence    		A foreign agent (character) failed when attempting an action against a garrison residence (garrison_residence) of the subject faction.

    Parameters:

    1

    string

    faction key

    Returns:

    1. nil

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

    Back to top

    Benchmark Scripts

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

    Parameters:

    1

    function

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

    2

    string

    Cindy file to show for the benchmark.

    3

    number

    Benchmark duration in seconds.

    4

    number

    Start x position of camera.

    5

    number

    Start y position of camera.

    6

    number

    Start distance of camera.

    7

    number

    Start bearing of camera (in radians).

    8

    number

    Start height of camera.

    Returns:

    1. nil

    Example:

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

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

Last updated 25/08/2021 12:07:49