Episodic Scripting

The episodic scripting interface is one of the two main interface provided by the campaign model to script. Unlike the campaign model hierarchy, which is used to query the state of the model, the episodic scripting interface is primarily used to make changes to the model.

The original documentation for the episodic scripting interface can be found here: Episodic Scripting interface. Note that a campaign must be loaded to generate this documentation.

Loaded in Campaign loaded in campaign
Back to top

Creation and Usage

This interface is automatically created and cached by the campaign_manager when the NewSession event is triggered. This happens very early in the loading sequence. Once created, functions on the episodic scripting interface may be called by calling the campaign manager.

Example - Specification:

-- assumes a campaign manager object called cm
cm:dismiss_advice()
Back to top

Character Lookups

Many function on the campaign manager perform actions on a character and/or the military force he or she commands. The character to perform the action on is commonly specified by a character lookup string. A character lookup string must be composed from one or more filters. See the table below for a list of filter types.

filter namedescription
factionFaction key, from the factions table.
typeAgent type, from the agent_types table.
abilityAgent ability, from the abilities table.
forenameForename, from the names table.
surnameSurname, from the names table.
xDisplay x co-ordinate - must be used in conjection with a y display co-ordinate and a radius.
yDisplay y co-ordinate - must be used in conjection with an x display co-ordinate and a radius.
rRadius around specified x/y display position.
garrisonSettlement name of a garrison to look in, from the campaign_map_settlements table.
character_cqiThe command queue index of a character. This is always unique.

Should the filters specified in the character lookup string return more than one eligible character then only the first of these is used in the function call. Generally, it's a good idea to ensure that filters will only return one character, so it's strongly recommended to solely use the character_cqi filter which will only ever match one character.

A filter may be specified in the lookup string in the form <filter_name>:<filter_value>. Multiple filters may be specified in a lookup string, separated by a comma. Furthermore, the campaign manager function campaign_manager:char_lookup_str can also be used to convert a character object, or its cqi number, into a character lookup string.

Example - Add trait to a character from the Achilles faction at a display position [123,456]:

cm:force_add_trait("faction:troy_main_dan_achilles,x:123,y:456,r:1", "trait_general_good", true)

Example - Remove all action points from a character with cqi 45:

cm:zero_action_points("character_cqi:45")

Example - Use the char_lookup_str function to disable movement for the faction leader of the Aetolians:

local char_grn_faction_leader = cm:get_faction("troy_main_dan_aetolians"):faction_leader()
cm:disable_movement_for_character(cm:char_lookup_str(char_grn_faction_leader))
Back to top

General Querying

cm:is_new_game()
Returns true if this a new campaign game, or false otherwise. A new game is one that has yet to be saved and reloaded.

Returns:

  1. boolean is new game

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 51

cm:is_benchmark_mode()
Returns true if this campaign is running in benchmark mode, meaning it was launched from the benchmark section in the graphics options.

Returns:

  1. boolean is benchmark mode

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 56

cm:model()
Returns a handle to the campaign model object.

Returns:

  1. userdata campaign model

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 61

cm:filesystem_lookup()
Perform a VFS lookup in the specified path (root is the data folder) for files matching the pattern. Returns a comma-delimited list of files found.

Returns:

  1. string file list

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 66

cm:compare_localised_string(uicomponent uicomponent, string label string)

Returns whether the supplied label string matches the text of a supplied uicomponent, taking localisation into account.

Parameters:

1

uicomponent

uicomponent

2

string

label string

Returns:

  1. boolean localisation matches

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 71

Back to top

Saving and Loading

cm:save_named_value(string value name, data value to save, context context object)

Write a value to the savegame. This should only be called when the SavingGame event is received, and must be passed the context object supplied by that event.
It's recommended to use the saving functions provided by the campaign manager, listed in the Saving Game section of this documentation, instead of directly calling this function.

Parameters:

1

string

Value name.

2

data

Value to save. Can be a boolean, number or string.

3

context

context object

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 91

cm:load_named_value(string value name, data default value, context context object)

Reads a value from a loading game. Should only be called when the LoadingGame event is received, and must be passed the context object supplied by that event.
It's recommended to use the loading functions provided by the campaign manager, listed in the Loading Game section of this documentation, instead of directly calling this function.

Parameters:

1

string

Value name.

2

data

This defines the type of the value to load from the savegame and also a default value which will be returned if no value with the specified name could be found in the savegame. Can be a boolean, number or string.

3

context

context object

Returns:

  1. data saved value, either a boolean, number or string.

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 99

cm:disable_saving_game(boolean should disable)

Prevents or allows the saving of the game.

Parameters:

1

boolean

should disable

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 108

cm:autosave_at_next_opportunity()
Autosave the game at the next opportunity.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 113

Back to top

Time Triggers

The functions described in this section grant raw access to the creation and removal of time triggers in campaign. While it's possible to use them directly it is highly recommended to use the wrapper functions provided by the campaign_manager object in script. These are listed in the Timer Callbacks section of this documentation.

cm:add_time_trigger(string id, number interval, [boolean repeat])

Register a time trigger, in seconds. This will cause a TimeTrigger event to trigger after the specified interval.

Parameters:

1

string

ID for this time trigger. This will be supplied with the TimeTrigger event when it is triggered.

2

number

Interval after which to trigger the TimeTrigger event, in seconds.

3

boolean

optional, default value=false

Repeats the time trigger if set to true.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 127

cm:remove_time_trigger(string id)

Removes a time trigger by string id.

Parameters:

1

string

id

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 134

Back to top

Ending Turn

cm:disable_end_turn(boolean should disable)

Prevents or allows ending turn.

Parameters:

1

boolean

should disable

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 147

cm:end_turn([boolean force])

Ends the turn for the current faction, optionally forcing at the next opportunity. This optional flag should only be set for a player faction.

Parameters:

1

boolean

optional, default value=false

force

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 152

cm:set_ai_uses_human_display_speed(boolean use human speed )

Forces or un-forces any characters visible to humans to move at normal speed during the end-turn sequence. Overrides set using this function are saved into the savegame.

Parameters:

1

boolean

use human speed

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 157

Back to top

Advisor

cm:dismiss_advice()
Dismisses the advisor panel.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 172

cm:dismiss_advice_at_end_turn(boolean should dismiss)

Set whether or not advice should be dismissed on ending turn.

Parameters:

1

boolean

should dismiss

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 176

Back to top

Camera

The functions in this section make use of camera co-ordinates. These are specified by five numeric components:

  1. display x co-ordinate of camera target

  2. display y co-ordinate of camera target

  3. horizontal distance from target to camera

  4. horizontal bearing in radians of target from camera

  5. height of camera

Example - scroll_camera_with_direction usage:

Example of cm:scroll_camera_with_direction usage showing multiple groups of co-ordinates supplied in table containers.
cm:scroll_camera_with_direction(true, 7, {490.8, 276.6, 5.6, 1.01, 4.0}, {491.0, 276.0, 5.6, 1.59, 4.0})

cm:set_camera_position(number x, number y, number d, number b, number h)

Repositions the camera to the specified co-ordinates.

Parameters:

1

number

Display x co-ordinate of camera target.

2

number

Display y co-ordinate of camera target.

3

number

Horizontal distance from camera to target.

4

number

Horizontal bearing in radians of target from camera.

5

number

Height of camera.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 201

cm:get_camera_position()
Returns the current position of the camera in format xyz position, xyz target.

Returns:

  1. number x, Display x co-ordinate of camera position.
  2. number y, Display y co-ordinate of camera position.
  3. number z, Display z co-ordinate of camera position.
  4. number x, Display x co-ordinate of camera target.
  5. number y, Display y co-ordinate of camera target.
  6. number z, Display z co-ordinate of camera target.

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 210

cm:get_camera_position_cindy_format()
Returns the current position of the camera.

Returns:

  1. number x, Display x co-ordinate of camera target.
  2. number y, Display y co-ordinate of camera target.
  3. number d, Horizontal distance from camera to target.
  4. number b, Horizontal bearing in radians of target from camera.
  5. number h, Height of camera.

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 220

cm:scroll_camera(boolean adjust endpoint, number scroll time, vararg co-ordinate list)

Scroll the camera along a spline.

Parameters:

1

boolean

Adjust the endpoint to be valid for gameplay. Set this to true if control is to be restored to the player after this camera movement finishes. Set to false if another camera movement follows this one.

2

number

Scroll time in seconds

3

vararg

Vararg list of co-ordinates. Each co-ordinate must be specified in a table containing four number co-ordinate components.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 229

cm:scroll_camera_with_direction(boolean adjust endpoint, number scroll time, vararg co-ordinate list)

Scroll the camera along a list of co-ordinates that define a spline.

Parameters:

1

boolean

Adjust the endpoint to be valid for gameplay. Set this to true if control is to be restored to the player after this camera movement finishes. Set to false if another camera movement follows this one.

2

number

Scroll time in seconds

3

vararg

Vararg list of co-ordinates. Each co-ordinate must be specified in a table containing five number co-ordinate components.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 236

cm:stop_camera()
Stops a scrolling camera.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 243

cm:fade_scene(number brightness, number duration)

Fades the scene to black or back to picture over a specified period.

Parameters:

1

number

Brightness, as a unary value. Supply a value of 0 to fade to black, supply a value of 1 to fade to picture, or supply a value in between to transition to a partially-faded picture.

2

number

Duration of the fade effect in seconds.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 247

Back to top

Movies and Cinematics

cm:register_instant_movie(string movie path)

Plays a fullscreen movie, by path from the data/Movies directory.

Parameters:

1

string

movie path

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 261

cm:register_outro_movie(string movie path)

Plays a fullscreen movie for an outro, by path from the data/Movies directory. The campaign will exit once playback has completed.

Parameters:

1

string

movie path

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 266

cm:play_movie_in_ui(string movie path)

Plays a movie in the movie panel, by path from the data/Movies directory.

Parameters:

1

string

movie path

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 271

cm:cinematic()
Returns a cinematic script interface.

Returns:

  1. cinematics cinematic interface

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 276

Back to top

UI Manipulation

cm:override_ui(string ui override name, boolean activate override)

Activates or deactivates a ui override.

Parameters:

1

string

ui override name

2

boolean

activate override

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 291

cm:stop_user_input(boolean stop input)

Stops or allows user input.

Parameters:

1

boolean

stop input

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 297

cm:steal_user_input(boolean steal input)

Steals user input, so that input notifications are redirected to script. When keypresses are stolen by script the game calls a function called OnKeyPressed when a keypress occurs. This function can be declared in script to receive these notifications.

Parameters:

1

boolean

steal input

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 302

cm:steal_escape_key(boolean steal escape key)

Steals the ESC key, so that keypresses on it are redirected to script. When keypresses are stolen by script the game calls a function called OnKeyPressed when a keypress occurs. This function can be declared in script to receive these notifications.

Parameters:

1

boolean

steal escape key

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 307

cm:enable_ui(boolean enable ui)

Enables or disables the entire user interface.

Parameters:

1

boolean

enable ui

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 312

cm:disable_shortcut(string component id, string function id, boolean should disable)

Disables or re-enables a shortcut by name. Shortcuts can be looked up in data/text/default_keys.xml.

Parameters:

1

string

Component id, specified by the component attibute of a func element.

2

string

Function id, specified by the name attribute of a func element.

3

boolean

Should disable.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 317

cm:disable_all_shortcuts(boolean disable)

Disable or enable all shortcuts.

Parameters:

1

boolean

disable

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 324

cm:add_unit_model_overrides(string character lookup, string model key)

Swap a model for a certain character. This needs to be set up at a new session.

Parameters:

1

string

Character lookup string - see Character Lookups for more information.

2

string

model key

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 329

cm:highlight_movement_extents(boolean should highlight)

Causes movement extents surrounded a selected character in the game to flash or not.

Parameters:

1

boolean

should highlight

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 335

cm:highlight_selected_character_zoc(boolean should highlight)

Causes the zone of control surrounding a selected character in the game to flash or not.

Parameters:

1

boolean

should highlight

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 340

cm:shown_message()
Return true if any message boxes are currently displayed

Returns:

  1. boolean messages displayed

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 345

cm:pending_auto_show_messages()
Return true if any auto shown messages are queued

Returns:

  1. boolean messages queued

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 350

Back to top

Markers, VFX and Composite Scenes

cm:add_marker(string marker id, string marker type, number x, number y, number height)

Add a marker at a specified display position, using a specified marker type. These markers are distinct from VFX in that they are generally 2D, clickable UI elements at a position on the battlefield.

Parameters:

1

string

Unique id for this marker, by which it may be later removed.

2

string

Marker type. Supported marker types are move_to, select, pointer, move_to_vfx, select_vfx, look_at_vfx and objective.

3

number

x display position.

4

number

y display position.

5

number

height above water plane.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 363

cm:remove_marker(string marker id)

Removes a marker previously added using cm:add_marker, by marker id.

Parameters:

1

string

marker id

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 372

cm:add_interactable_campaign_marker(
  string unique id,
  string marker info,
  number x,
  number y,
  number radius,
  string faction key,
  string subculture key
)

Add an interactable campaign marker of a specified type to the campaign map at a specified location. A radius around the marker is specified. As matching campaign characters enter or leave this radius then AreaEntered/AreaExited events will be triggered.
Subculture and faction keys can be specified in order to filter what campaign characters should trigger the proximity events.
Interactable campaign markers can be used for game features such as encounters at sea.

Parameters:

1

string

Unique id for this campaign marker, by which it may be later removed with cm:remove_interactable_campaign_marker.

2

string

Marker info key. This should match a record from the campaign_interactable_marker_infos table.

3

number

Logical x position for the marker.

4

number

Logical y position for the marker.

5

number

Radius around the position at which to trigger AreaEntered/AreaExited events.

6

string

Faction key filter. A blank string can be supplied to omit this.

7

string

Subculture key filter. A blank string can be supplied to omit this.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 377

cm:remove_interactable_campaign_marker(string unique id)

Removes an interactable campaign marker that was previously added with cm:add_interactable_campaign_marker, by unique id.

Parameters:

1

string

unique id

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 390

cm:add_vfx(string vfx id, string vfx, number x, number y, number height)

Adds a vfx of a specified type at a specified display position. VFX are distinct from markers in that they are generally 3D graphical effects.

Parameters:

1

string

Unique id for this vfx, by which it may later be removed with cm:remove_vfx.

2

string

VFX type. This must be an entry from the vfx_event field of the campaign_vfx_lookups table.

3

number

x display position.

4

number

y display position.

5

number

height above water plane.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 395

cm:remove_vfx(string vfx id)

Removes a vfx previously added with cm:add_vfx, by vfx id.

Parameters:

1

string

vfx id

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 404

cm:add_character_vfx(number character cqi, string vfx, boolean show in shroud)

Adds a vfx to a specified character.

Parameters:

1

number

Command queue index of the character.

2

string

VFX type. This must be an entry from the vfx_event field of the campaign_vfx_lookups table.

3

boolean

Show this vfx even when the character is under the shroud.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 409

cm:remove_character_vfx(number character cqi, string vfx)

Removes a vfx from a specified character.

Parameters:

1

number

Command queue index of the character.

2

string

VFX type. This must be an entry from the vfx_event field of the campaign_vfx_lookups table.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 416

cm:add_garrison_residence_vfx(number garrison residence cqi, string vfx, boolean show in shroud)

Adds a vfx to a specified garrison residence/settlement.

Parameters:

1

number

Command queue index of the garrison residence.

2

string

VFX type. This must be an entry from the vfx_event field of the campaign_vfx_lookups table.

3

boolean

Show this vfx even when the garrison residence is under the shroud.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 422

cm:remove_garrison_residence_vfx(number character cqi, string vfx)

Removes a vfx from a specified character.

Parameters:

1

number

Command queue index of the character.

2

string

VFX type. This must be an entry from the vfx_event field of the campaign_vfx_lookups table.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 429

cm:add_scripted_composite_scene_to_logical_position(
  string name,
  string composite scene,
  number x,
  number x,
  number facing x,
  number facing y,
  boolean one shot,
  boolean show in seen shroud,
  boolean show in unseen shroud
)

Adds a composite scene at a specified logical position.

Parameters:

1

string

Unique name for this composite scene, by which it may later be removed with cm:remove_scripted_composite_scene.

2

string

Composite scene key from the campaign_composite_scenes table.

3

number

Logical x co-ordinate.

4

number

Logical y co-ordinate.

5

number

Logical x co-ordinate of a position this composite scene faces.

6

number

Logical y co-ordinate of a position this composite scene faces.

7

boolean

One shot - if set to true, this composite scene is not added to the internal list of scenes and can't later be removed with cm:remove_scripted_composite_scene. However, the name of one-shot scenes does not have to be unique.

8

boolean

Sets whether this composite scene should be drawn when in thin shroud over previously-seen terrain.

9

boolean

Sets whether this composite scene should be drawn when in thick shroud over unseen terrain.

Returns:

  1. boolean action successful

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 435

cm:add_scripted_composite_scene_to_settlement(
  string name,
  string composite scene,
  string settlement key,
  number facing x,
  number facing y,
  boolean one shot,
  boolean show in seen shroud,
  boolean show in unseen shroud
)

Adds a composite scene to a specified settlement.

Parameters:

1

string

Unique name for this composite scene, by which it may later be removed with cm:remove_scripted_composite_scene.

2

string

Composite scene key from the campaign_composite_scenes table.

3

string

Key of settlement to add the scene to, from the campaign_map_settlements table.

4

number

Logical x co-ordinate of a position this composite scene faces.

5

number

Logical y co-ordinate of a position this composite scene faces.

6

boolean

One shot - if set to true, this composite scene is not added to the internal list of scenes and can't later be removed with cm:remove_scripted_composite_scene. However, the name of one-shot scenes does not have to be unique.

7

boolean

Sets whether this composite scene should be drawn when in thin shroud over previously-seen terrain.

8

boolean

Sets whether this composite scene should be drawn when in thick shroud over unseen terrain.

Returns:

  1. boolean action successful

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 449

cm:add_scripted_composite_scene_to_settlement_port(
  string name,
  string composite scene,
  string settlement key,
  number facing x,
  number facing y,
  boolean one shot,
  boolean show in seen shroud,
  boolean show in unseen shroud
)

Adds a composite scene to the port slot of a specified settlement.

Parameters:

1

string

Unique name for this composite scene, by which it may later be removed with cm:remove_scripted_composite_scene.

2

string

Composite scene key from the campaign_composite_scenes table.

3

string

Key of settlement to add the scene to, from the campaign_map_settlements table.

4

number

Logical x co-ordinate of a position this composite scene faces.

5

number

Logical y co-ordinate of a position this composite scene faces.

6

boolean

One shot - if set to true, this composite scene is not added to the internal list of scenes and can't later be removed with cm:remove_scripted_composite_scene. However, the name of one-shot scenes does not have to be unique.

7

boolean

Sets whether this composite scene should be drawn when in thin shroud over previously-seen terrain.

8

boolean

Sets whether this composite scene should be drawn when in thick shroud over unseen terrain.

Returns:

  1. boolean action successful

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 462

cm:remove_scripted_composite_scene(string name)

Removes a composite scene previously added by script, by the unique name given.

Parameters:

1

string

name

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 475

Back to top

Shroud

The shroud is the fog of war covering areas on the campaign map that have yet to be seen. The shroud on a region - the area surrounding and associated with a settlement - may be either covered, seen or visible.

  • Covered regions are shown with thick shroud which obscures land features, settlements and characters.

  • Seen regions are shown with thin shroud through which settlements and land features are shown, but not characters.

  • Visible regions are fully displayed.

The following functions allow some manipulation of the shroud. In all cases, the shroud is recalculated during the end-turn sequence, so modifications to the shroud are lost and have to re-applied at the start of the round or player's turn.

cm:show_shroud(boolean show)

Enables or disables the shroud.

Parameters:

1

boolean

show

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 495

cm:take_shroud_snapshot()
Caches the state of the shroud across the map, so that it may later be recalled with cm:restore_shroud_from_snapshot.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 500

cm:restore_shroud_from_snapshot()
Restores the state of the shroud across the map after it has been cached with cm:take_shroud_snapshot.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 504

cm:make_neighbouring_regions_visible_in_shroud()
Makes all neighbouring regions visible in the shroud, for all factions. This effect will persist until the next round.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 508

cm:make_neighbouring_regions_seen_in_shroud()
Makes all neighbouring regions seen in the shroud, for all factions. This effect will persist until the next round.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 512

cm:make_region_visible_in_shroud(string faction key, string region key)

Removes the shroud from a specified land region for a specific faction. The region specified must be a land region.

Parameters:

1

string

Faction key, from the factions table.

2

string

Region key, from the campaign_map_regions table.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 516

cm:make_region_seen_in_shroud(string faction key, string region key)

Sets the shroud state of a specified land region to seen, for a specific faction. The region specified must be a land region.

Parameters:

1

string

Faction key, from the factions table.

2

string

Region key, from the campaign_map_regions table.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 522

cm:make_sea_region_visible_in_shroud(string region key)

Removes the shroud from a specified sea region for all factions.

Parameters:

1

string

Region key, from the campaign_map_regions table.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 528

cm:make_sea_region_seen_in_shroud(string region key)

Sets the shroud state of a specified sea region for all factions to seen. The specified region must be a sea region.

Parameters:

1

string

Region key, from the campaign_map_regions table.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 533

cm:disable_movement_for_ai_under_shroud(string player faction key, string ai faction key)

Removes all action points for characters from the specified target faction if they are hidden under the shroud of the specified player faction. This is a one-time action, and should be called each turn if it's desired that AI movement for a faction be stopped until 'discovered' by the player.

Parameters:

1

string

player faction key

2

string

ai faction key

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 538

cm:disable_shopping_for_ai_under_shroud(boolean should disable)

Prevents all factions hidden under the shroud from constructing or repairing buildings. Unlike other functions documented here this is a game-wide toggle and does not need to be set each turn. This should only be used in a singleplayer game.

Parameters:

1

boolean

should disable

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 544

Back to top

Character and Military Force Creation

cm:create_force(
  string faction key,
  string unit list,
  string region key,
  number x,
  number y,
  string id,
  boolean exclude unique characters,
  boolean command queue
)

Creates an army or a navy at the specified position, belonging to the specified faction, with the specified list of units. If the faction doesn't exist on the campaign map then it will also be created.

Parameters:

1

string

Faction key from the factions table.

2

string

Unit list. This should be a comma-separated list of unit keys from the main_units table.

3

string

Region in which the force is created, from the campaign_map_regions table.

4

number

Logical x co-ordinate.

5

number

Logical y co-ordinate.

6

string

ID of force. A ScriptedForceCreated event is triggered once the military force is created, and this ID is included in the context of the event so that listening scripts can differentiate between multiple created forces.

7

boolean

Prevent this force from having a unique character appointed as its general.

8

boolean

Send this command via the command queue. Setting this to true will cause a delay of a game tick or two before the force is created.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 557

cm:create_force_with_general(
  string faction key,
  string unit list,
  string region key,
  number x,
  number y,
  string character type,
  string character subtype,
  string forename,
  string clanname,
  string surname,
  string other name,
  string id,
  boolean make faction leader
)

Creates an army or a navy commanded by a specified character at the specified position, belonging to the specified faction, with the specified list of units. If the faction doesn't exist on the campaign map then it will also be created.

Parameters:

1

string

Faction key from the factions table.

2

string

Unit list. This should be a comma-separated list of unit keys from the main_units table.

3

string

Region in which the force is created, from the campaign_map_regions table.

4

number

Logical x co-ordinate.

5

number

Logical y co-ordinate.

6

string

Character type key, from the agents table.

7

string

Character subtype key, from the agent_subtypes table.

8

string

Forename id. This should be a value from the id field of the names table.

9

string

Clan name id. This should be a value from the id field of the names table. This can be used to grant a title such as "Admiral" or "Emperor". A blank string may be supplied to omit this.

10

string

Surname id. This should be a value from the id field of the names table. A blank string may be supplied to omit this.

11

string

Other name id. This should be a value from the id field of the names table. This is currently unused and should be set to a blank string.

12

string

ID of force. A ScriptedForceCreated event is triggered once the military force is created, and this ID is included in the context of the event so that listening scripts can differentiate between multiple created forces.

13

boolean

Make this character the faction leader.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 569

cm:create_force_with_existing_general(
  string character lookup,
  string faction key,
  string unit list,
  string region key,
  number x,
  number y,
  string id
)

Creates an army or a navy commanded by a specified existing character at the specified position, belonging to the specified faction, with the specified list of units.

Parameters:

1

string

Character lookup string specifying the character to appoint as force commander. See Character Lookups for more information.

2

string

Faction key from the factions table.

3

string

Unit list. This should be a comma-separated list of unit keys from the main_units table.

4

string

Region in which the force is created, from the campaign_map_regions table.

5

number

Logical x co-ordinate.

6

number

Logical y co-ordinate.

7

string

ID of force. A ScriptedForceCreated event is triggered once the military force is created, and this ID is included in the context of the event so that listening scripts can differentiate between multiple created forces.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 586

cm:create_force_with_full_diplomatic_discovery(
  string faction key,
  string unit list,
  string region key,
  number x,
  number y,
  string id,
  boolean exclude unique characters,
  boolean command queue
)

Creates an army or a navy commanded by a specified existing character at the specified position, belonging to the specified faction, with the specified list of units.
This command is distinct from cm:create_force in that it forces factions who can see the created force to be diplomatically aware of the force's faction.

Parameters:

1

string

Faction key from the factions table.

2

string

Unit list. This should be a comma-separated list of unit keys from the main_units table.

3

string

Region in which the force is created, from the campaign_map_regions table.

4

number

Logical x co-ordinate.

5

number

Logical y co-ordinate.

6

string

ID of force. A ScriptedForceCreated event is triggered once the military force is created, and this ID is included in the context of the event so that listening scripts can differentiate between multiple created forces.

7

boolean

Prevent this force from having a unique character appointed as its general.

8

boolean

Send this command via the command queue. Setting this to true will cause a delay of a game tick or two before the force is created.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 597

cm:create_agent(
  string faction key,
  string agent type,
  string agent subtype,
  number x,
  number y,
  string id,
  boolean command queue
)

Create an agent/hero character at a specified position.

Parameters:

1

string

Faction key from the factions table.

2

string

Agent type from the agents table.

3

string

Agent subtype from the agent_subtypes table.

4

number

Logical x co-ordinate.

5

number

Logical y co-ordinate.

6

string

ID of agent. A ScriptedAgentCreated event is triggered once the character is created, and this ID is included in the context of the event so that listening scripts can differentiate between multiple created agents.

7

boolean

Send this command via the command queue. Setting this to true will cause a delay of a game tick or two before the force is created.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 610

cm:spawn_unique_agent(number faction cqi, string agent key, boolean force)

Creates a unique agent.

Parameters:

1

number

Faction cqi.

2

string

Agent record key, from the unique_agents table.

3

boolean

Force agent to spawn even if invalid.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 621

cm:spawn_unique_agent_at_region(number faction cqi, string agent key, number region cqi, boolean force)

Creates a unique agent in a specified region.

Parameters:

1

number

Faction cqi.

2

string

Agent record key, from the unique_agents table.

3

number

The cqi of the target region.

4

boolean

Force agent to spawn even if invalid.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 628

cm:spawn_unique_agent_at_character(
  number faction cqi,
  string agent key,
  number character cqi,
  boolean force
)

Creates a unique agent at or near the position of a specified character.

Parameters:

1

number

Faction cqi.

2

string

Agent record key, from the unique_agents table.

3

number

The cqi of the target character.

4

boolean

Force agent to spawn even if invalid.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 636

cm:spawn_character_to_pool(
  string faction,
  string forename,
  string surname,
  string clanname,
  string othername,
  number age,
  boolean male,
  string agent key,
  string agent subtype key,
  boolean immortal,
  string art set
)

Spawns a new character in the specified faction's recruitment pool.

Parameters:

1

string

Faction key, from the factions table.

2

string

Forename key. This should be a value from the id field of the names table.

3

string

Surname key. This should be a value from the id field of the names table. A blank string may be supplied to omit this.

4

string

Clan name key. This should be a value from the id field of the names table. This can be used to grant a title such as "Admiral" or "Emperor". A blank string may be supplied to omit this.

5

string

Other name key. This should be a value from the id field of the names table. This is currently unused and should be set to a blank string.

6

number

Age of character.

7

boolean

Set this character to be male or female.

8

string

Agent record key, from the agents table.

9

string

Agent subtype key, from the agent_subtypes table.

10

boolean

Sets whether this character is immortal.

11

string

Art set override id, from the campaign_character_art_sets table. A blank string may be supplied to omit this.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 644

cm:spawn_character_into_family_tree(
  string faction,
  string forename,
  string surname,
  string clanname,
  string othername,
  number age,
  boolean male,
  string father,
  string mother,
  boolean immortal,
  string art set,
  boolean make heir
)

Spawns a new character into a position in the family tree of the specified faction.

Parameters:

1

string

Faction key, from the factions table.

2

string

Forename key. This should be a value from the id field of the names table.

3

string

Surname key. This should be a value from the id field of the names table. A blank string may be supplied to omit this.

4

string

Clan name key. This should be a value from the id field of the names table. This can be used to grant a title such as "Admiral" or "Emperor". A blank string may be supplied to omit this.

5

string

Other name key. This should be a value from the id field of the names table. This is currently unused and should be set to a blank string.

6

number

Age of character.

7

boolean

Set this character to be male or female.

8

string

Character lookup string specifying the father of the spawned character. For more information see the documentation on Character Lookups.

9

string

Character lookup string specifying the mother of the spawned character. For more information see the documentation on Character Lookups.

10

boolean

Sets whether this character is immortal.

11

string

Art set override id, from the campaign_character_art_sets table. A blank string may be supplied to omit this.

12

boolean

Make this character the faction heir.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 659

cm:find_valid_spawn_location_for_character_from_settlement(
  string faction key,
  string region key,
  boolean on sea,
  boolean in same region,
  [number preferred spawn distance]
)

Utilises the pathfinder to locate and return a valid spawn point for a character, based around a settlement. Returns -1, -1 if invalid.

Parameters:

1

string

Faction key, from the factions table.

2

string

Region key of settlement, from the campaign_map_regions table.

3

boolean

Specifies whether the position should be on the sea.

4

boolean

Specifies whether the spawn location should be in the same region as the specified settlement.

5

number

optional, default value=0

Specifies the distance at which the character should spawn.

Returns:

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

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 675

cm:find_valid_spawn_location_for_character_from_position(
  string faction key,
  number x,
  number y,
  boolean in same region,
  [number preferred distance]
)

Utilises the pathfinder to locate and return a valid spawn point for a character, based around a position. Returns -1, -1 if invalid.

Parameters:

1

string

Faction key, from the factions table.

2

number

Logical x co-ordinate of position around which to search.

3

number

Logical y co-ordinate of position around which to search.

4

boolean

Specifies whether the spawn location should be in the same region as the specified position.

5

number

optional, default value=0

Preferred spawn distance, in logical hexes.

Returns:

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

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 686

cm:find_valid_spawn_location_for_character_from_character(
  string faction key,
  string character lookup,
  boolean in same region,
  [number preferred distance]
)

Utilises the pathfinder to locate and return a valid logical spawn point for a character, based around another character. Returns -1, -1 if invalid.

Parameters:

1

string

Faction key, from the factions table.

2

string

Character lookup string of subject character. For more information see the documentation on Character Lookups.

3

boolean

Specifies whether the spawn location should be in the same region as the specified character.

4

number

optional, default value=0

Preferred spawn distance, in logical hexes.

Returns:

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

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 697

cm:appoint_character_to_most_expensive_force(string character lookup)

Appoints the specified character to the command of the most expensive military force in their faction.

Parameters:

1

string

Character lookup string of subject character. For more information see the documentation on Character Lookups.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 707

cm:lock_starting_general_recruitment(string startpos id, string faction key)

Locks recruitment of a starting general, preventing them from being created from the recruitment pool. This also works for characters that are convalescing. The character must be specified by startpos id.

Parameters:

1

string

Startpos id of the target character. This is looked up from the ID field of the start_pos_characters table. This function cannot be used to lock recruitment of a character not present in the startpos data.

2

string

Faction key of the character, from the factions table.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 712

cm:unlock_starting_general_recruitment(string startpos id, string faction key)

Unlocks recruitment of a starting general, allowing them to be recruited. This also works for characters that are convalescing. The character must be specified by startpos id.

Parameters:

1

string

Startpos id of the target character. This is looked up from the ID field of the start_pos_characters table. This function cannot be used to unlock recruitment of a character not present in the startpos data.

2

string

Faction key of the character, from the factions table.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 718

cm:add_units_to_faction_mercenary_pool(number faction cqi, string unit key, number count)

Adds one or more of a specified unit to the specified faction's mercenary pool.

Parameters:

1

number

CQI of the subject faction.

2

string

Unit key, from the main_units table.

3

number

Number of units to add.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 724

cm:num_units_in_faction_mercenary_pool(number faction cqi, string unit key)

Return count of a specified unit in the factions mercenary pool.

Parameters:

1

number

CQI of the subject faction.

2

string

Unit key, from the main_units table.

Returns:

  1. number count, Number of units in the faction mercenary pool.

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 731

cm:add_units_to_province_mercenary_pool_by_region(string region key, string unit key, number count)

Adds one or more of a specified unit to the specified province mercenary pool. The province is specified by a region within it.

Parameters:

1

string

Region key of a region within the target province, from the campaign_map_regions table.

2

string

Unit key, from the main_units table.

3

number

Number of units to add.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 738

cm:add_unit_to_faction_mercenary_pool(
  FACTION_SCRIPT_INTERFACE faction script interface,
  string unit key,
  number count,
  number replenishment chance percentage,
  number max units,
  number max units replenished per turn,
  number xp level,
  string faction restricted record,
  string subculture restricted record,
  string tech restricted record
)

Add a unit to the specified factions mercenary pool. Will replace any existing entry with the same unit record.

Parameters:

1

FACTION_SCRIPT_INTERFACE

The faction object

2

string

The unit key from the table land_units

3

number

The amount of units to add to the mercenary pool

4

number

5

number

The max amount of units that can be in the pool

6

number

The max amount of units that can be replenished in the pool per turn

7

number

The level of the units when recruited

8

string

[Optional]

9

string

[Optional]

10

string

[Optional]

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 745

cm:add_unit_to_province_mercenary_pool(
  REGION_SCRIPT_INTERFACE region script interface,
  string unit key,
  number count,
  number replenishment chance percentage,
  number max units,
  number max units replenished per turn,
  number xp level,
  string faction restricted record,
  string subculture restricted record,
  string tech restricted record
)

Adds one or more of a specified unit to the specified province mercenary pool. The province is specified by a region within it.

Parameters:

1

REGION_SCRIPT_INTERFACE

The region object

2

string

The unit key from the table land_units

3

number

The amount of units to add to the mercenary pool

4

number

5

number

The max amount of units that can be in the pool

6

number

The max amount of units that can be replenished in the pool per turn

7

number

The level of the units when recruited

8

string

[Optional]

9

string

[Optional]

10

string

[Optional]

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 759

cm:force_remove_siege_equipment(MILITARY_FORCE_SCRIPT_INTERFACE force)
Clears construction queue and removes all constructed siege equipment from the specified military force

Parameters:

1

MILITARY_FORCE_SCRIPT_INTERFACE

force

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 773

Back to top

Character Manipulation

The functions in this section all give order or manipulate the state of characters in the game. They make extensive use of Character Lookups.

cm:add_agent_experience(string character lookup, number points)

Adds experience points to a specified character.

Parameters:

1

string

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

2

number

Experience points to award.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 786

cm:add_experience_to_units_commanded_by_character(string character lookup, number level)

Increases the experience of all units commanded by a specified character, by a specified level.

Parameters:

1

string

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

2

number

Level to increase experience of units by.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 792

cm:add_experience_to_unit(number unit_cqi, number level)

Increase the experience of the given unit, by a specified level.

Parameters:

1

number

The cqi of the unit

2

number

Level to increase experience of unit by.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 797

cm:set_character_experience_disabled(boolean disable)

Disables or re-enables characters gaining experience across the whole campaign. This restriction is saved into the savegame, so only needs to be set once.

Parameters:

1

boolean

Disable experience. Set to false to re-enable.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 802

cm:grant_unit_to_character(string character lookup, string unit key)

Create and add a specifiec unit to a military force commanded by a specified character. The unit will only be created if there is room for it in the force.

Parameters:

1

string

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

2

string

Key of unit to create, from the main_units table.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 807

cm:grant_unit_to_character_above_limit(string character lookup, string unit key, number count)

Create and add a unit (specified by the unit key) to a character's army. The unit will be created even if their is no room for the unit in the force. Returns a table with the new units cqis'.

Parameters:

1

string

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

2

string

Key of unit to create, from the main_units table.

3

number

Number of untis to be added

Returns:

  1. table CQIs of the created units

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 812

cm:remove_unit_by_cqi(number cqi The cqi of the unit that should be destroyed)

Destroy the unit with the specified cqi.

Parameters:

1

number

cqi The cqi of the unit that should be destroyed

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 819

cm:move_to(string character lookup, number x, number y, boolean command queue)

Orders the specified character to move to a specified logical position. This is equivalent to the player or AI issuing the same order, and as such should only be done on that faction's turn.
Note that if the character is in a settlement, or the intended destination is a settlement, an enemy army, or another kind of special obstacle then it's likely that a different type of order is required - see cm:join_garrison, cm:leave_garrison and cm:attack, for example.

Parameters:

1

string

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

2

number

Logical x co-ordinate of target position.

3

number

Logical y co-ordinate of target position.

4

boolean

Send the order via the command queue. This causes a short delay before the order is actually given.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 823

cm:cancel_actions_for(string character lookup)

Immediately cancels the current actions of a specified character.

Parameters:

1

string

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

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 832

cm:teleport_to(string character lookup, number x, number y, boolean command queue)

Orders the specified character to immediately teleport to a specified logical position. This order should only be given on that faction's turn.

Parameters:

1

string

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

2

number

Logical x co-ordinate of target position.

3

number

Logical y co-ordinate of target position.

4

boolean

Send the order via the command queue. This causes a short delay before the order is actually given.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 837

cm:join_garrison(string character lookup, string settlement)

Orders the specified character to move into a specified garrison residence. The garrison is specified by settlement key. This is equivalent to the player or AI issuing the same order, and as such should only be done on that faction's turn.

Parameters:

1

string

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

2

string

Key of settlement containing the garrison residence, from the campaign_map_settlements table.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 845

cm:leave_garrison(string character lookup, string settlement)

Make the specified garrisoned character leave their garrison and move to a specified logical positon. Orders the specified character to move into a specified garrison residence. The garrison is specified by settlement key.

Parameters:

1

string

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

2

string

Key of settlement containing the garrison residence, from the campaign_map_settlements table.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 851

cm:attack(string character lookup, string target character lookup, boolean command queue)

Orders the specified character to attack a target character. This is equivalent to the player or AI issuing the same order, and as such should only be done on that faction's turn.

Parameters:

1

string

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

2

string

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

3

boolean

Send the order via the command queue. This causes a short delay before the order is actually given.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 857

cm:attack_region(string character lookup, string region key, boolean command queue)

Orders the specified character to initiate an attack on the settlement in a target region. If the character cannot initiate a battle (for example he or she currently has no method to defeat the fortifications) then nothing will happen.

Parameters:

1

string

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

2

string

Region key containing the target settlement, from the campaign_map_regions table.

3

boolean

Send the order via the command queue. This causes a short delay before the order is actually given.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 864

cm:seek_exchange(
  string character lookup,
  string target character lookup,
  boolean show ui,
  boolean command queue
)

Orders one character to seek a unit exchange with a target character, allowing troops to be swapped between the two armies they command.

Parameters:

1

string

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

2

string

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

3

boolean

Shows the seek exchange UI.

4

boolean

Send the order via the command queue. This causes a short delay before the order is actually given.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 871

cm:replenish_action_points(string character lookup)

Replenishes the action points of a specified character.

Parameters:

1

string

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

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 879

cm:zero_action_points(string character lookup)

Removes all action points from a specified character.

Parameters:

1

string

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

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 884

cm:kill_character(string character lookup, boolean destroy force, boolean command queue)

Kills a specified character, and optionally also the entire military force they command.

Parameters:

1

string

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

2

boolean

Destroy the character and the entire military force they command.

3

boolean

Send the order via the command queue. This causes a short delay before the order is actually given.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 889

cm:kill_character_and_commanded_unit(
  string character lookup,
  boolean destroy force,
  boolean command queue
)

Kills a specified character and their associated unit, and optionally also the entire military force they command.

Parameters:

1

string

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

2

boolean

Destroy the character and the entire military force they command.

3

boolean

Send the order via the command queue. This causes a short delay before the order is actually given.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 896

cm:kill_character_and_commanded_unit_with_dt(
  string character lookup,
  boolean destroy force,
  boolean command queue,
  string death type
)

Kills a specified character and their associated unit with a death type, and optionally also the entire military force they command.

Parameters:

1

string

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

2

boolean

Destroy the character and the entire military force they command.

3

boolean

Send the order via the command queue. This causes a short delay before the order is actually given.

4

string

Death type from the death_types table.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 903

cm:wound_character(string character lookup, number convalescence time, boolean command queue)

Wounds a specified character, forcing them to convalesce for a specified number of turns before they can be re-appointed.

Parameters:

1

string

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

2

number

Number of turns this character should convalesce for until they can be re-appointed.

3

boolean

Send the order via the command queue. This causes a short delay before the order is actually given.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 911

cm:character_forced_invisible(string character lookup, boolean invisibility)

Makes the character invisible or turns them back to visible.

Parameters:

1

string

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

2

boolean

invisibility

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 918

cm:force_agent_action_success_for_human(boolean force success)

Force the local player's faction to succeed at all agent actions.

Parameters:

1

boolean

force success

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 924

cm:force_character_force_into_stance(string character lookup, string stance key)

Forces the military force commanded by the specified character into the specified stance.

Parameters:

1

string

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

2

string

Stance key, from the campaign_stances table.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 929

cm:set_only_allow_basic_recruit_stance(boolean force basic recruitment stances)

Stops all military forces from entering non-default recruitment stances, such as raiding camp stance.

Parameters:

1

boolean

force basic recruitment stances

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 935

cm:remove_unit_from_character(string character lookup, string unit key)

Remove the first instance of the specified unit from the force commanded by the specified character.

Parameters:

1

string

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

2

string

Key of unit to remove, from the main_units table.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 940

cm:set_character_immortality(string character lookup, boolean is immortal)

Sets whether the specified character can die or not.

Parameters:

1

string

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

2

boolean

is immortal

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 946

cm:set_character_unique(string character lookup, boolean is unique)

Sets whether the specified character is unique or not. This affects several aspects about how the game might treat that character such as when they might be available to recruit.

Parameters:

1

string

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

2

boolean

is unique

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 952

cm:add_attack_of_opportunity_overrides(string character lookup, boolean force attack)

Forces a specified character to always or never perform an attack of opportunity, meaning they will always/never intercept when they get the chance. Once in place, this override can be removed with cm:remove_attack_of_opportunity_overrides.

Parameters:

1

string

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

2

boolean

Force an attack - if set to true the target character will always intercept, if set to false the character will always decline to intercept.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 958

cm:remove_attack_of_opportunity_overrides(string character lookup)

Removes any attack of opportunity override previously placed on the target character with cm:add_attack_of_opportunity_overrides.

Parameters:

1

string

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

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 964

cm:force_normal_character_locomotion_speed_for_turn(boolean is_enabled)

Forces any characters visible to humans to move at normal speed during the current turn if parameter is set to true.

Parameters:

1

boolean

Is normal speed enabled

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 969

cm:faction_apply_character_loyalty_change(
  string faction key,
  string trait key,
  number loyalty change,
  number threshold
)

Change the loyalty of all characters in the given faction, having a given trait (if not empty string), by a given value w/o crossing a given threshold (that should have the same sign as the loyalty change).

Parameters:

1

string

Faction key from the factions table.

2

string

Trait key from the character_traits table.

3

number

Loyalty change

4

number

[Optional] Threshhold

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 974

cm:apply_character_loyalty_change(number character cqi, number loyalty change, number threshold)

Change the character's loyalty by a given amount w/o crossing a given threshold (that should have the same sign as the loyalty change).

Parameters:

1

number

Command-queue index of the target character.

2

number

Loyalty change

3

number

[Optional] Threshhold

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 982

cm:get_character(string character lookup)

Get a character's CHARACTER_SCRIPT_INTERFACE from a lookup string. For more information, see Character Lookups.

Parameters:

1

string

Lookup string for the character

Returns:

  1. CHARACTER_SCRIPT_INTERFACE character

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 989

cm:spawn_rogue_army(string faction key, number x, number y)

Spawn a rogue army, will fail if the rogue army is alive or is flagged to naturally spawn.

Parameters:

1

string

Faction key, from the factions table.

2

number

X coordinate on the campaign map.

3

number

Y coordinate on the campaign map.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 995

cm:activate_stance_to_force(boolean allow, string stance key, number military force cqi)

Allow or disallow a military force from using a certain stance.

Parameters:

1

boolean

Whether to allow or disallow a stance.

2

string

Stance key from table campaign_stances.

3

number

Command-queue index of the military force.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1002

cm:replenish_units(string character lookup, number factor)

Replenish units for the specified character.

Parameters:

1

string

Character lookup string

2

number

Amount of hp to replenish as a percentage. Valid values are from 0.0 to 1.0

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1009

cm:damage_garrison_units(string region key, number damage amount)

Damages any units in the target garrison.

Parameters:

1

string

Region key from the table regions

2

number

Damage amount as a percantage.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1015

cm:force_character_to_leave(number character cqi)

Forces the character to leave it's faction.

Parameters:

1

number

Command-queue index for the character

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1021

cm:set_character_scripted_time_to_leave(CHARACTER_SCRIPT_INTERFACE character, number time to live)
Sets the supplied character's scripted time to leave to the supplied number. This is displayed on the army banner as well.

Parameters:

1

CHARACTER_SCRIPT_INTERFACE

Character we wish to leave.

2

number

How many turns from now should the character leave.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1026

cm:set_custom_army_info_icon(
  number military_force_cqi,
  string icon_id ,
  string icon_path,
  string tooltip_title_key,
  string tooltip_desc_key,
  number param1,
  number param2,
  number param3
)

Sets the icon path and the tooltip of a custom icon in the army name plate on the campaign map. If you want normal tooltip, specify an empty string for the tooltip_desc_key. Not saved, entirely managed by scripts.

Parameters:

1

number

2

string

icon_id

3

string

icon_path

4

string

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

5

string

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

6

number

[Optional] Number to be used for formatting.

7

number

[Optional] Number to be used for formatting.

8

number

[Optional] Number to be used for formatting.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1032

cm:set_custom_army_info_icon_visibility(number military_force_cqi, string icon_id, boolean visible)

Shows or hides a custom icon in the army name plate on the campaign map, that was previously added via cm:set_custom_army_info_icon.
Not saved, entirely managed by scripts.

Parameters:

1

number

military_force_cqi

2

string

icon_id

3

boolean

visible

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1044

Back to top

Area Triggers

cm:add_circle_area_trigger(
  number x,
  number y,
  number radius,
  string trigger name,
  string character lookup,
  boolean trigger on enter,
  boolean trigger on exit,
  boolean trigger once
)

Establishes a circular area trigger monitor around a specified display position, with a specified character lookup string filter. This monitor will trigger an AreaEntered or AreaExited script event if a character that matches the specified filter moves through the specified circular area boundary.

Parameters:

1

number

x display co-ordinate.

2

number

y display co-ordinate.

3

number

Radius of circle.

4

string

Trigger name. Multiple trigger areas with the same name behave as a single trigger.

5

string

Character lookup string, specifying characters for which this trigger area will fire events. For more information, see Character Lookups.

6

boolean

Specifies whether an AreaEntered event is fired when a matching character enters the trigger area.

7

boolean

Specifies whether an AreaExited event is fired when a matching character exits the trigger area.

8

boolean

Specifies whether the trigger continues monitoring after it fires its first event.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1059

cm:add_outline_area_trigger(
  string trigger name,
  string character lookup,
  boolean trigger on enter,
  boolean trigger on exit,
  boolean trigger once,
  ... co-ordinates
)

Establishes a area trigger monitor around a specified display position, with a specified character lookup string filter. The shape of the trigger area is specified by a series of supplied points. This monitor will trigger an AreaEntered or AreaExited script event if a character that matches the specified filter moves through the specified circular area boundary.

Parameters:

1

string

Trigger name. Multiple trigger areas with the same name behave as a single trigger.

2

string

Character lookup string, specifying characters for which this trigger area will fire events. For more information, see Character Lookups.

3

boolean

Specifies whether an AreaEntered event is fired when a matching character enters the trigger area.

4

boolean

Specifies whether an AreaExited event is fired when a matching character exits the trigger area.

5

boolean

Specifies whether the trigger continues monitoring after it fires its first event.

6

...

Variable number of display co-ordinates, each supplied as an indexed table containing an x and y co-ordinate.

Returns:

  1. nil

Example:

cm:add_outline_area_trigger(
    "test_trigger",
    "character_cqi:123",
    true,
    false,
    true,
    true,
    {0, 0},
    {0, 100},
    {100, 100},
    {100, 0}
);

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1071

cm:remove_area_trigger(string trigger name)

Removes any area triggers established with the supplied name.

Parameters:

1

string

trigger name

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1093

Back to top

Traits, Skills and Ancillaries

cm:force_add_trait(
  string character lookup,
  string trait key,
  [number trait points],
  [boolean command queue]
)

Grant the specified trait to the specified character. If the character already has the trait, a trait point will be added.

Parameters:

1

string

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

2

string

Trait key, from the character_traits table.

3

number

optional, default value=1

Number of trait points to add.

4

boolean

optional, default value=true

Issue this command via the command queue.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1107

cm:force_remove_trait(string character lookup, string trait key)

Removes the specified trait from the specified character. If the character is past the point of no return in the trait, it will be removed anyway.

Parameters:

1

string

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

2

string

Trait key, from the character_traits table.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1115

cm:force_remove_all_traits(string character lookup)

Remove all traits from the specified character. If the character is past the point of no return in a trait, it will be removed anyway.

Parameters:

1

string

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

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1121

cm:force_add_ancillary(string character lookup, string ancillary key)

Grant the specified ancillary to the specified character.

Parameters:

1

string

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

2

string

Ancillary key, from the ancillaries table.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1126

cm:force_add_and_equip_ancillary(string character lookup, string ancillary key)

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

Parameters:

1

string

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

2

string

Ancillary key, from the ancillaries table.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1132

cm:force_remove_ancillary(string character lookup, string ancillary key, boolean remove to pool)

Remove the specified ancilliary from the specified character.

Parameters:

1

string

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

2

string

Ancillary key, from the ancillaries table.

3

boolean

Removes the ancillary from the character but leaves it in the pool of available ancillaries.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1138

cm:add_ancillary_to_faction(string faction key, string ancillary key, boolean display event)

Grants the specified ancillary to the specified faction. The ancillary goes into that faction's ancillary pool, from where it may be equipped by a character.

Parameters:

1

string

Faction key, from the factions table.

2

string

Ancillary key, from the ancillaries table.

3

boolean

Sets whether the associated event feed event should be displayed.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1145

cm:force_remove_ancillary_from_faction(string faction key, string ancillary key)

Remove all instances of the specified ancillary from every character, and the shared ancillary pool, of the specified faction.

Parameters:

1

string

Faction key, from the factions table.

2

string

Ancillary key, from the ancillaries table.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1152

cm:force_add_skill(string character lookup, string skill key)

Grant the specified skill to the specified character, or adds a point if they already have it.

Parameters:

1

string

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

2

string

Skill key, from the character_skills table.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1158

cm:force_reset_skills(string character lookup)

Completely resets the skill points of the target character. Does not remove background skills.

Parameters:

1

string

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

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1164

cm:set_non_scripted_traits_disabled(boolean disable)

Prevents or allows the application of traits by effect.trait, which is intended to be the general-purpose trait-adding function. cm:force_add_trait will still work even with this restriction in place.

Parameters:

1

boolean

disable

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1169

cm:set_non_scripted_ancillaries_disabled(boolean disable)

Prevents or allows the application of ancillaries by effect.ancillary, which is intended to be the general-purpose ancillary-adding function. cm:force_add_ancillary will still work even with this restriction in place.

Parameters:

1

boolean

disable

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1174

cm:add_trait_to_character_by_family_member(
  number family member cqi,
  string trait key,
  boolean show message,
  [trait 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.

Parameters:

1

number

family member cqi

2

string

trait key

3

boolean

show message

4

trait

optional, default value=1

points

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1179

Back to top

Province and Faction Mechanics

cm:set_tax_rate(string faction key, number tax rate)

Sets the tax rate for a specified faction. The tax rate may be one of the following integer values:

ValueDescription
0minimal
1low
2normal
3high
4extortionate

Parameters:

1

string

Faction key, from the factions table.

2

number

Tax rate, from the table above.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1197

cm:exempt_region_from_tax(string region key, boolean exempt)

Exempts, or un-exempts, the province containing specified region from tax contributions.

Parameters:

1

string

Region key, from the campaign_map_regions table.

2

boolean

Exempt province from tax.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1209

cm:exempt_province_from_tax_for_all_factions_and_set_default(string region key, boolean exempt)

Exempt the province containing specified region from tax for all factions that own a settlement within it, and set the default for future factions.

Parameters:

1

string

Region key, from the campaign_map_regions table.

2

boolean

Exempt province from tax.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1215

cm:disable_rebellions_worldwide(boolean disable)

Disables or re-enables all rebellions across the map.

Parameters:

1

boolean

disable

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1221

cm:force_rebellion_in_region(string region key, number units, number x, number y, boolean suppress message)

Force a rebellion of a specified size in the specified region.

Parameters:

1

string

Region key, from the campaign_map_regions table.

2

number

Maximum number of units in the spawned rebellion.

3

number

Logical x co-ordinate of target position.

4

number

Logical y co-ordinate of target position.

5

boolean

Suppress the event message related to the rebellion.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1226

cm:treasury_mod(string faction key, number amount)

Immediately modifies the treasury of the specified faction by the specified amount.

Parameters:

1

string

Faction key, from the factions table.

2

number

Treasury modification. This value must be positive.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1235

cm:set_public_order_of_province_for_region(string region key, number public order)

Sets the public order value for the province containing the specified region.

Parameters:

1

string

Region key, from the campaign_map_regions table.

2

number

Public order value.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1241

cm:set_public_order_disabled_for_province_for_region(string region key, boolean disable)

Disables or re-enables public order in the province containing the specified region.

Parameters:

1

string

Region key, from the campaign_map_regions table.

2

boolean

Disable public order.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1247

cm:set_public_order_disabled_for_province_for_region_for_all_factions_and_set_default(
  string region key,
  boolean disable
)

Disables or re-enables public order in the province containing the specified region, for all factions that own settlements within the province, including factions that capture territory there in the future.

Parameters:

1

string

Region key, from the campaign_map_regions table.

2

boolean

Disable public order.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1253

cm:add_development_points_to_region(string region key, number development points)

Adds development points to the province containing the specified region.

Parameters:

1

string

Region key, from the campaign_map_regions table.

2

number

Developments points to add.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1259

cm:set_imperium_level_change_disabled(boolean disable)

Disables or re-enables imperium level changes across the whole campaign.

Parameters:

1

boolean

disable

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1265

cm:set_region_abandoned(string region key)

Immediately sets the specified to be abandoned. Nothing will happen if an already-abandoned region is specified.

Parameters:

1

string

Region key, from the campaign_map_regions table.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1270

cm:transfer_region_to_faction(string region key, string faction key)

Immediately transfers ownership of the specified region to the specified faction.

Parameters:

1

string

Region key, from the campaign_map_regions table.

2

string

Faction key, from the factions table.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1275

cm: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, from the campaign_map_regions table.

2

number

Storm strength. The strength of existing storm instances can be looked up in the campaign_storms table.

3

number

Duration of the storm in turns.

4

string

optional, default value=false

Storm type, looked up from the campaign_storm_types table. By default, this is set to "land_storm" for a land region and "wandering_decaying_sea_storm" for a sea region.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1281

cm:set_technology_research_disabled(boolean disable)

Disable or re-enable technology functionality in game for the player.

Parameters:

1

boolean

disable

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1289

cm:set_liberation_options_disabled(boolean disable)

Disables or re-enables post-battle liberation options for the player.

Parameters:

1

boolean

disable

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1294

cm:set_ui_notification_of_victory_disabled(boolean disable)

Disable or re-enable notification of victory for the UI.

Parameters:

1

boolean

disable

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1299

cm:remove_god_from_conflict(string god key)

Remove god from conflict by given god record key.

Parameters:

1

string

God key from the campaign_gods table.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1304

cm:politics_get_ministerial_posts(string faction key, number tier, boolean taken)

Gets the amount of ministerial posts that are available or unavailable in a given tier.

Parameters:

1

string

Faction key, from the factions table.

2

number

The tier in which to check for posts. -1 for all tiers

3

boolean

Whether to check for available or unavailable posts

Returns:

  1. number ministerial posts, The number of available or unavailable posts for the given tier

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1309

cm:politics_enabled(string faction key)

Checks if politics feature is enabled for faction

Parameters:

1

string

Faction key, from the factions table.

Returns:

  1. boolean enabled, Whether the politics feature is enabled or not.

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1317

cm:set_battle_details_override_for_region(
  string region key,
  string battle type,
  string redirection,
  string redirection_catchment,
  string time of day
)

Override the battle details for battles of the given type in the specified region (empty string for any if you want to default it). Pass 'suffix' for redirection_catchment if you want to use redirection as a suffix to the default map.

Parameters:

1

string

Region to override.

2

string

Override battle type.

3

string

Battle folder override.

4

string

Redirection catchement by key, make sure it's valid for the supplied battle type and battel folder combination.

5

string

Time of day override, valid options are empty string, "day" or "night".

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1323

cm:set_can_autoresolve_settlement_battle(
  string settlement key,
  boolean can_autoresolve,
  [string tooltip loc path]
)

Sets a flag weather attacker can autoresolve settlement battles for the supplied settlement by key.

Parameters:

1

string

Settlement to set the flag for.

2

boolean

New value for the flag.

3

string

optional, default value=nil] string tooltip loc path, Localisation key for the autoresolve button. This should be supplied in the full [table]_[field]_[key

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

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1332

cm:set_custom_settlement_info_icon(
  string region_key,
  string icon_id,
  string icon_path,
  string tooltip_title_key,
  string tooltip_desc_key,
  number param1,
  number param2,
  number param3
)

Sets the icon path and the tooltip key of a custom icon in the settlement name plate on the campaign map. Not saved, entirely managed by scripts.

Parameters:

1

string

region_key

2

string

icon_id

3

string

icon_path

4

string

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

5

string

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

6

number

[Optional] Number to be used for formatting.

7

number

[Optional] Number to be used for formatting.

8

number

[Optional] Number to be used for formatting.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1339

cm:set_custom_settlement_info_icon_visibility(string region_key, string icon_id, boolean visible)

Shows or hides a custom icon in the settlement name plate on the campaign map, that was previously added via cm:set_custom_settlement_info_icon.
Not saved, entirely managed by scripts.

Parameters:

1

string

region_key

2

string

icon_id

3

boolean

visible

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1351

cm:set_fight_battle_at_night(string faction_key, boolean is_night_battle)

Sets/unsets the battle to be fought at night, goes through CCQ.

Parameters:

1

string

faction_key

2

boolean

is_night_battle

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1359

cm:set_force_has_retreated_this_turn(CHARACTER_SCRIPT_INTERFACE character)
Sets the has reatreated flag for the specified character

Parameters:

1

CHARACTER_SCRIPT_INTERFACE

character

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1365

cm:set_skip_all_but_current(boolean skip)

Enables / disables playing for all other faction. Avoid using in multiplayer.

Parameters:

1

boolean

skip

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1370

cm:set_unit_script_name_by_cqi(number unit_cqi, string script_name)

Set the script name (for usage in battle) for a unit by cqi.

Parameters:

1

number

unit_cqi

2

string

script_name

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1375

cm:upgrade_unit(number unit_cqi, string unit_key)

Force a unit by CQI to upgrade to a unit by record.

Parameters:

1

number

Unit to upgrade.

2

string

Target unit record key.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1381

cm:set_region_supply_points(string region_key, number new_supply_points)

Set region's supply points

Parameters:

1

string

Target region record key.

2

number

New supply points value.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1386

Back to top

Missions

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

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.

Parameters:

1

string

Faction key, from the factions table.

2

string

Mission key, from the missions table.

3

boolean

Set the mission to fire immediately, instead of waiting for the start of the faction's turn. This also overrides any delay set in the mission data.

4

boolean

optional, default value=false

Trigger the mission via the command queue or not.

Returns:

  1. boolean mission triggered successfully

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1396

cm:trigger_custom_mission(string faction key, string mission key, [boolean use command queue])

Triggers a specific custom mission from its database record key. This mission must be defined in the missions.txt file that accompanies each campaign.

Parameters:

1

string

Faction key, from the factions table.

2

string

Mission key, from missions.txt file.

3

boolean

optional, default value=false

Trigger the mission via the command queue or not.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1405

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

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.

Parameters:

1

string

Faction key, from the factions table.

2

string

Mission definition string.

3

boolean

optional, default value=false

Trigger the mission via the command queue or not.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1412

cm:cancel_mission(string faction key, string mission key, [boolean use command queue], [boolean is custom])

Cancels an active mission.

Parameters:

1

string

Faction key, from the factions table.

2

string

Mission key, from the missions table.

3

boolean

optional, default value=false

Sends the command via the command queue or not.

4

boolean

optional, default value=false

Is the mission to be cancelled a custom mission.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1419

cm:trigger_mission_with_targets(
  number faction cqi,
  string mission key,
  string target faction cqi,
  string secondary faction cqi,
  string character cqi,
  string military force cqi,
  string region cqi,
  string settlement cqi
)

Attempts to trigger a mission from database records with one or more target game objects. The game object or objects to associate the mission with are specified by command-queue index. The mission will need to pass any conditions set up in the cdir_events_mission_option_junctions table in order to trigger.
A value of 0 may be supplied to omit a particular type of target.

Parameters:

1

number

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

2

string

Mission key, from the missions table.

3

string

Command-queue index of a target faction. 0 may be specified to omit this target (and other target arguments following this one).

4

string

Command-queue index of a second target faction. May be 0.

5

string

Command-queue index of a target character. May be 0.

6

string

Command-queue index of a target military force. May be 0.

7

string

Command-queue index of a target region. May be 0.

8

string

Command-queue index of a target settlement. May be 0.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1427

cm:toggle_mission_generation(boolean can generate)

Sets whether the campaign director system can generate missions or not.

Parameters:

1

boolean

can generate

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1440

Back to top

Scripted Missions

Campaign missions may be set up with a mission type of SCRIPTED. In this case, it is the responsibility of script to manage and complete the mission's objectives. The scripted mission_manager object provides an interface for the easy creation of missions of this type. The functions listed here are the code functions that the mission manager and other scripts can use to manage scripted missions.

cm:set_scripted_mission_text(string mission key, string script key, string text key)

Updates the text shown for a particular objective of a specified scripted mission. This can be used to update a representation of mission progress on the panel.

Parameters:

1

string

Mission key, from the missions table.

2

string

Key of the particular scripted objective associated with the mission.

3

string

Localised text key, in the full [table]_[field]_[key] format.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1455

cm:set_scripted_mission_position(string mission key, string script key, number x, number y)

Updates the map position related to a particular objective of a specified scripted mission. This can be used to update a mission's zoom-to target.

Parameters:

1

string

Mission key, from the missions table.

2

string

Key of the particular scripted objective associated with the mission.

3

number

Logical x co-ordinate of the updated position.

4

number

Logical y co-ordinate of the updated position.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1462

cm:complete_scripted_mission_objective(
  string mission key,
  string script key,
  boolean is success,
  string custom_id
)

Marks a particular objective associated with a specified scripted mission as either succeeded or failed. Once all objectives for a scripted mission are completed, the mission itself is completed.

Parameters:

1

string

Mission key, from the missions table.

2

string

Key of the particular scripted objective associated with the mission.

3

boolean

Objective was completed successfully.

4

string

Custom ID of the mission.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1470

Back to top

Incidents & Dilemmas

cm:trigger_incident(string faction key, string incident key, boolean fire immediately)

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.

Parameters:

1

string

Faction key, from the factions table.

2

string

Incident key, from the incidents table.

3

boolean

Set the incident to fire immediately.

Returns:

  1. boolean incident was triggered

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1487

cm:trigger_custom_incident(
  string faction key,
  string incident key,
  boolean fire immediately,
  string payload
)

Forces an incident to trigger. A payload string fragment specifying the incident consequences must be supplied.

Parameters:

1

string

Faction key, from the factions table.

2

string

Incident key, from the dilemmas table.

3

boolean

Set the incident to fire immediately.

4

string

Payload string. Check missions.txt for examples of how to structure a payload string.

Returns:

  1. nil

Example:

cm:trigger_custom_incident("troy_main_dan_achilles", "troy_main_test_incident", true, "payload{ faction_pooled_resource_transaction{resource troy_food;factor troy_resource_factor_faction;amount 5000;}"}");

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1495

cm:trigger_incident_with_targets(
  number faction cqi,
  string incident key,
  string target faction cqi,
  string secondary faction cqi,
  string character cqi,
  string military force cqi,
  string region cqi,
  string settlement cqi
)

Attempts to trigger an incident from database records with one or more target game objects. The game object or objects to associate the incident with are specified by command-queue index. The incident will need to pass any conditions set up in the cdir_events_incident_option_junctions table in order to trigger.
A value of 0 may be supplied to omit a particular type of target.

Parameters:

1

number

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

2

string

Incident key, from the incidents table.

3

string

Command-queue index of a target faction. 0 may be specified to omit this target (and other target arguments following this one).

4

string

Command-queue index of a second target faction. May be 0.

5

string

Command-queue index of a target character. May be 0.

6

string

Command-queue index of a target military force. May be 0.

7

string

Command-queue index of a target region. May be 0.

8

string

Command-queue index of a target settlement. May be 0.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1504

cm:toggle_incident_generation(boolean can generate)

Sets whether the campaign director system can generate dilemmas or not.

Parameters:

1

boolean

can generate

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1517

cm:trigger_dilemma(string faction key, string dilemma key, boolean fire immediately)

Instructs the campaign director to attempt to trigger a dilemma with a particular key, based on dilemma records from the database. The dilemma will be triggered if its conditions, defined in the cdir_events_dilemma_option_junctions, pass successfully. The function returns whether the dilemma was successfully triggered or not.

Parameters:

1

string

Faction key.

2

string

Dilemma key, from the dilemma table.

3

boolean

Set the incident to fire immediately.

Returns:

  1. boolean dilemma was triggered

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1522

cm:trigger_custom_dilemma(
  string faction key,
  string dilemma key,
  string first choice payload,
  string second choice payload
)

Triggers a custom dilemma with two choices, with the specified faction as the dilemma target.

Parameters:

1

string

Faction key, from the factions table.

2

string

Dilemma key, from the dilemmas table.

3

string

Payload key for the first choice of the dilemma, from the cdir_events_dilemma_payloads table.

4

string

Payload key for the second choice of the dilemma, from the cdir_events_dilemma_payloads table.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1530

cm: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
)

Attempts to trigger a dilemma from database records with one or more target game objects. 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.
A value of 0 may be supplied to omit a particular type of target.

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

Command-queue index of a target faction. 0 may be specified to omit this target (and other target arguments following this one).

4

number

Command-queue index of a second target faction. May be 0.

5

number

Command-queue index of a target character. May be 0.

6

number

Command-queue index of a target military force. May be 0.

7

number

Command-queue index of a target region. May be 0.

8

number

Command-queue index of a target settlement. May be 0.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1538

cm:toggle_dilemma_generation(boolean can generate)

Sets whether the campaign director system can generate dilemmas or not.

Parameters:

1

boolean

can generate

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1551

Back to top

Events and Suppression

cm:enable_auto_generated_missions(boolean enable)

Enable or disable non-scripted missions.

Parameters:

1

boolean

enable

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1566

cm:set_event_generation_enabled(boolean enable)

Enables or disables random event generation by the campaign director system.

Parameters:

1

boolean

enable

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1571

cm:show_message_event(
  string faction key,
  string title loc key,
  string primary loc key,
  string secondary loc key,
  boolean persistent,
  number index
)

Constructs and displays an event message.

Parameters:

1

string

Key of the faction to whom the event is targeted, from the factions table.

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. Persistent events are saved to the event history which is accessible to the player.

6

number

Index indicating the type of event. This can be looked up by first finding a record in event_feed_message_events which relates to the event message being shown, then looking up the value in the campaign_groups field of this record in the campaign_group_member_criteria_values. This will provide one or more possible index values that may be used here.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1576

cm:show_configurable_message_event(
  string faction key,
  string title loc key,
  string primary loc key,
  string secondary loc key,
  number index,
  number param1,
  number param2,
  number param3
)

Show a configurable message event with the specified title, primary detail and secondary detail to the specified faction. You can configure their behavior by editing the scripted_persistent_configurable_event record.

Parameters:

1

string

Key of the faction to whom the event is targeted, from the factions table.

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

Index indicating the type of event. This can be looked up by first finding a record in event_feed_message_events which relates to the event message being shown, then looking up the value in the campaign_groups field of this record in the campaign_group_member_criteria_values. This will provide one or more possible index values that may be used here.

6

number

[Optional] Number parameter for formatting.

7

number

[Optional] Number parameter for formatting.

8

number

[Optional] Number parameter for formatting.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1586

cm: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
)

Constructs and displays a event message with a zoom-to location.

Parameters:

1

string

Key of the faction to whom the event is targeted, from the factions table.

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. Persistent events are saved to the event history which is accessible to the player.

8

number

Index indicating the type of event. This can be looked up by first finding a record in event_feed_message_events which relates to the event message being shown, then looking up the value in the campaign_groups field of this record in the campaign_group_member_criteria_values. This will provide one or more possible index values that may be used here.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1599

cm:suppress_all_event_feed_event_types(boolean activate suppression)

Activates or deactivates the episodic scripting event feed suppression system. Once activated, event messages of all types will be withheld from triggering until they are either whitelisted with cm:whitelist_event_feed_event_type or until suppression is lifted again with a subsequent call to this function. Once one of these two actions occurs, any event messages previously blocked will be triggered.
See also the equivalent UI-side suppression function CampaignUI.SuppressAllEventTypesInUI. This function should be used with care, as it can cause softlocks if dilemmas are suppressed. The UI-side functions are generally safer to use.
Message suppression using this system should not be maintained over the end-turn sequence.

Parameters:

1

boolean

activate suppression

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1611

cm:whitelist_event_feed_event_type(string event type)

Whitelists an event type, allowing it to be shown despite suppression being activated with cm:suppress_all_event_feed_event_types. Event types are specified by a compound key from the event_feed_targeted_events table, by concatenating the values from the event and target fields from that table. See the documentation for the ui-side equivalent of this function, CampaignUI.WhiteListEventTypeInUI, for more information.
This function has no effect if suppression has not been activated with cm:suppress_all_event_feed_event_types.

Parameters:

1

string

Event type, specified with a compound key from the event_feed_targeted_events table.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1618

cm:event_feed_event_type_pending(string event type)

Returns whether any event messages of the supplied type are currently being blocked/withheld by event feed suppression. If this function returns true for a specified event type, then the withheld event messages may be shown by calling cm:whitelist_event_feed_event_type to lift the suppression on that event type, or by calling cm:suppress_all_event_feed_event_types to lift all suppression.

Parameters:

1

string

Event type, specified with a compound key from the event_feed_targeted_events table.

Returns:

  1. boolean event is currently pending

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1624

cm:disable_event_feed_events(
  boolean should disable,
  string category,
  string subcategory,
  string subcategory
)

Enable or disable event feed events by category, subcategory or event. Any of these types can be empty. This differs from event feed suppression in that messages blocked by this function will be discarded, never to be shown. This function is of most use for temporarily or momentarily blocking certain event messages that the game produces naturally for some reason. This function should be used with care, as it can cause a softlock if a dilemma is triggered while disabled.
Note that the event type lists are independent of one another, so if an event message is blocked by category, this restriction will not be lifted by unblocking by subcategory, for example.

Parameters:

1

boolean

Disable the event messages specified by the supplied filters. Supply false here to re-enable previously disabled event messages.

2

string

Event feed category to block, from the event_feed_categories table. Supply a blank string to not filter by category.

3

string

Event feed subcategory to block, from the event_feed_subcategories table. Supply a blank string to not filter by subcategory.

4

string

Event feed subcategory to block, from the event_feed_events table. Supply a blank string to not filter by event.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1630

cm:disable_all_event_feed_events(boolean should disable)

Enable or disable all event feed events.

Parameters:

1

boolean

True to disable, false to enable

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1639

cm:set_ignore_end_of_turn_public_order(
  boolean should disable,
  string category,
  string subcategory,
  string subcategory
)

Enable or disable event feed events by category, subcategory or event. Any of these types can be empty. This differs from event feed suppression in that messages blocked by this function will be discarded, never to be shown. This function is of most use for temporarily or momentarily blocking certain event messages that the game produces naturally for some reason. This function should be used with care, as it can cause a softlock if a dilemma is triggered while disabled.
Note that the event type lists are independent of one another, so if an event message is blocked by category, this restriction will not be lifted by unblocking by subcategory, for example.

Parameters:

1

boolean

Disable the event messages specified by the supplied filters. Supply false here to re-enable previously disabled event messages.

2

string

Event feed category to block, from the event_feed_categories table. Supply a blank string to not filter by category.

3

string

Event feed subcategory to block, from the event_feed_subcategories table. Supply a blank string to not filter by subcategory.

4

string

Event feed subcategory to block, from the event_feed_events table. Supply a blank string to not filter by event.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1644

Back to top

Buildings and Slots

cm:add_restricted_building_level_record(string building key)

Disallow the construction of a specific building
See also the function cm:remove_restricted_building_level_record.
See also the function cm:add_restricted_building_level_record_for_faction.
See also the function cm:remove_restricted_building_level_record_for_faction.

Parameters:

1

string

building key

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1662

cm:remove_restricted_building_level_record(string building key)

Allow the construction of a specific building again
See also the function cm:add_restricted_building_level_record.
See also the function cm:add_restricted_building_level_record_for_faction.
See also the function cm:remove_restricted_building_level_record_for_faction.

Parameters:

1

string

building key

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1670

cm:add_restricted_building_level_record_for_faction(string faction key, string building key)

Disallow the construction of a specific building for a specific faction
See also the function cm:add_restricted_building_level_record.
See also the function cm:remove_restricted_building_level_record.
See also the function cm:remove_restricted_building_level_record_for_faction.

Parameters:

1

string

faction key

2

string

building key

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1678

cm:remove_restricted_building_level_record_for_faction(string faction key, string building key)

Allow the construction of a specific building again for a specific faction
See also the function cm:add_restricted_building_level_record.
See also the function cm:remove_restricted_building_level_record.
See also the function cm:add_restricted_building_level_record_for_faction.

Parameters:

1

string

faction key

2

string

building key

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1687

cm:instantly_dismantle_building(string slot key)

Instantly dismantle the building in the specified slot. Slots keys are specified in the form <region_key>:<slot_number>, where the slot number is a zero-based integer index.
See also the campaign_manager function campaign_manager:instantly_dismantle_building_in_region.

Parameters:

1

string

slot key

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1696

cm:instantly_dismantle_foreign_slot_building(
  string region key,
  string faction key,
  number foreign slot index
)

Instantly dismantle the building in the foreign specified slot.

Parameters:

1

string

region key

2

string

faction key

3

number

foreign slot index

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1702

cm:instantly_upgrade_building(string slot key, string building key)

Instantly upgrade the building in the specified slot to the specified building key.
See also the campaign_manager function campaign_manager:instantly_upgrade_building_in_region.

Parameters:

1

string

Slot key specified in the form <region_key>:<slot_number>, where the slot number is a zero-based integer index.

2

string

Building key, from the building_levels table.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1709

cm:instantly_repair_building(string slot key)

Instantly repair the building in the specified slot. Slots keys are specified in the form <region_key>:<slot_number>, where the slot number is a zero-based integer index.

Parameters:

1

string

slot key

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1716

cm:instant_set_building_health_percent(string region key, string building key, number health percent)

Instantly set the health of a building.

Parameters:

1

string

Region key, from the campaign_map_regions table.

2

string

Building level or chain key, from either the building_levels or building_chains tables.

3

number

New health value of building, expressed as a number from 0 to 100.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1721

cm:set_building_can_repair(string region key, string building key, boolean can repair)

Overrides if a building can repair.

Parameters:

1

string

Region key, from the campaign_map_regions table.

2

string

Building level or chain key, from either the building_levels or building_chains tables.

3

boolean

Whether the building can repair or not

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1728

cm:complete_recruitment_and_contruction_in_region(string region key)

Instantly complete recruitment and construction in region.

Parameters:

1

string

Region key, from the campaign_map_regions table.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1735

cm:override_building_chain_display(
  string building chain key,
  string override chain key,
  [string region key]
)

Override the display of a building chain so that it appears as another building chain in the ui. A region key may optionally be specified to only override the building chain there. The override building chain must contain the same number of buildings as the chain being overridden.

Parameters:

1

string

Building chain key, from the building_chains table.

2

string

Override building chain key, also from the building_chains table.

3

string

optional, default value=nil

Region key, from the campaign_map_regions table.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1740

cm:add_building_to_force(number force cqi, string building key, boolean operation was successful)

Attempts to add a horde building to a military force. A slot must be available, or the force must contain a building that can be upgraded to the building specified.

Parameters:

1

number

Military force command-queue index value.

2

string

Building key, from the building_levels table.

3

boolean

operation was successful

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1747

cm:set_horde_save_buildings(string character loookup, boolean should save)

Set whether the horde commander retains the buildings if his army is destroyed

Parameters:

1

string

Character lookup string - see Character Lookups for more information.

2

boolean

Whether to save them or not

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1754

cm:remove_faction_foreign_slots_from_region(number faction cqi, number region cqi)

Removes the specified foreign slot set from the target region, for the target faction.

Parameters:

1

number

Command-queue index value of the target faction.

2

number

Command-queue index value of the target region.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1760

cm:add_settlement_model_override(string Settlement key, string Model name)

Use a different model for a settlement.

Parameters:

1

string

Settlement key

2

string

Model name

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1766

cm:add_building_model_override(string Slot key, string Building key, string Model name)

Use a different model for a slot, generated slots are named: settlement_army-admin, settlement_culture, settlement_government, settlement_navy-admin, settlement_ordnance, settlement_minor, settlement_fortification.

Parameters:

1

string

Slot key

2

string

Building key

3

string

Model name

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1772

cm:remove_settlement_model_override(string Settlement key)

Use the default model for the settlement.

Parameters:

1

string

Settlement key

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1779

cm:remove_building_model_override(string Slot key, string Building key)

Use the default model for the building.

Parameters:

1

string

Slot key

2

string

Building key

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1784

Back to top

Effect Bundles

Effects and effect bundles are the primary method by which campaign systems make gameplay balance modifications. The in-game benefits which technologies, buildings, rites and faction effects, amongst many other examples, are delivered through the activation of effect bundles.

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

Apply an effect bundle to a faction for a number of turns, or indefinitely.

Parameters:

1

string

Effect bundle key, from the effect_bundles table.

2

string

Faction key, from the factions table.

3

number

Number of turns to apply the effect bundle for. -1 may be supplied to apply the effect indefinitely.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1798

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

Removes a previously-applied effect bundle from a faction.

Parameters:

1

string

Effect bundle key, from the effect_bundles table.

2

string

Faction key, from the factions table.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1805

cm:apply_effect_bundle_to_character(string effect bundle key, number character cqi, number turns)

Apply an effect bundle to a character (by character cqi) for a number of turns (-1 turns means indefinitely).

Parameters:

1

string

Effect bundle key, from the effect_bundles table.

2

number

Command-queue index of the character

3

number

Number of turns to apply the effect bundle for. -1 may be supplied to apply the effect indefinitely.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1811

cm:remove_effect_bundle_from_character(string effect bundle key, number character cqi)

Remove a previously applied effect bundle from a character.

Parameters:

1

string

Effect bundle key, from the effect_bundles table.

2

number

Command-queue index of the character

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1818

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

Apply an effect bundle to a military force for a number of turns, or indefinitely.

Parameters:

1

string

Effect bundle key, from the effect_bundles table.

2

number

Command-queue index of the military force.

3

number

Number of turns to apply the effect bundle for. -1 may be supplied to apply the effect indefinitely.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1824

cm:remove_effect_bundle_from_force(string effect bundle key, number force cqi)

Removes a previously-applied effect bundle from a military force.

Parameters:

1

string

Effect bundle key, from the effect_bundles table.

2

number

Command-queue index of the military force.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1831

cm:apply_effect_bundle_to_characters_force(
  string effect bundle key,
  number character cqi,
  number turns,
  boolean command queue
)

Apply an effect bundle to a military force for a number of turns, or indefinitely. The military force is specified by its commanding character.

Parameters:

1

string

Effect bundle key, from the effect_bundles table.

2

number

Command-queue index of the character commanding the military force.

3

number

Number of turns to apply the effect bundle for. -1 may be supplied to apply the effect indefinitely.

4

boolean

Send this command via the command queue.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1837

cm:remove_effect_bundle_from_characters_force(string effect bundle key, number character cqi)

Removes a previously-applied effect bundle from a military force, specified by its commanding character.

Parameters:

1

string

Effect bundle key, from the effect_bundles table.

2

number

Command-queue index of the character commanding the military force.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1845

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

Apply an effect bundle to a campaign map region for a number of turns, or indefinitely.

Parameters:

1

string

Effect bundle key, from the effect_bundles table.

2

string

Region key, from the campaign_map_regions table.

3

number

Number of turns to apply the effect bundle for. -1 may be supplied to apply the effect indefinitely.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1851

cm:remove_effect_bundle_from_region(string effect bundle key, string region key)

Removes a previously-applied effect bundle from a campaign map region.

Parameters:

1

string

Effect bundle key, from the effect_bundles table.

2

string

Region key, from the campaign_map_regions table.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1858

cm:create_new_custom_effect_bundle(string effect bundle key)

Creates a new custom effect bundle from the specified effect bundle record.

Parameters:

1

string

Effect bundle key, from the effect_bundles table.

Returns:

  1. CUSTOM_EFFECT_BUNDLE_SCRIPT_INTERFACE custom effect bundle

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1864

cm:apply_custom_effect_bundle_to_faction(
  CUSTOM_EFFECT_BUNDLE_SCRIPT_INTERFACE effect bundle key,
  FACTION_SCRIPT_INTERFACE effect bundle key
)
Apply a custom effect bundle to a faction. Replaces any existing effect bundle with the same record.

Parameters:

1

CUSTOM_EFFECT_BUNDLE_SCRIPT_INTERFACE

Effect bundle key, from the effect_bundles table.

2

FACTION_SCRIPT_INTERFACE

Effect bundle key, from the effect_bundles table.

Returns:

  1. CUSTOM_EFFECT_BUNDLE_SCRIPT_INTERFACE custom effect bundle

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1870

cm:apply_custom_effect_bundle_to_character(
  CUSTOM_EFFECT_BUNDLE_SCRIPT_INTERFACE effect bundle key,
  CHARACTER_SCRIPT_INTERFACE effect bundle key
)
Apply a custom effect bundle to a character. Replaces any existing effect bundle with the same record.

Parameters:

1

CUSTOM_EFFECT_BUNDLE_SCRIPT_INTERFACE

Effect bundle key, from the effect_bundles table.

2

CHARACTER_SCRIPT_INTERFACE

Effect bundle key, from the effect_bundles table.

Returns:

  1. CUSTOM_EFFECT_BUNDLE_SCRIPT_INTERFACE custom effect bundle

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1877

cm:apply_custom_effect_bundle_to_force(
  CUSTOM_EFFECT_BUNDLE_SCRIPT_INTERFACE effect bundle key,
  MILITARY_FORCE_SCRIPT_INTERFACE effect bundle key
)
Apply a custom effect bundle to a force. Replaces any existing effect bundle with the same record.

Parameters:

1

CUSTOM_EFFECT_BUNDLE_SCRIPT_INTERFACE

Effect bundle key, from the effect_bundles table.

2

MILITARY_FORCE_SCRIPT_INTERFACE

Effect bundle key, from the effect_bundles table.

Returns:

  1. CUSTOM_EFFECT_BUNDLE_SCRIPT_INTERFACE custom effect bundle

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1884

cm:apply_custom_effect_bundle_to_characters_force(
  CUSTOM_EFFECT_BUNDLE_SCRIPT_INTERFACE effect bundle key,
  CHARACTER_SCRIPT_INTERFACE effect bundle key
)
Apply a custom effect bundle to a characters force. Replaces any existing effect bundle with the same record.

Parameters:

1

CUSTOM_EFFECT_BUNDLE_SCRIPT_INTERFACE

Effect bundle key, from the effect_bundles table.

2

CHARACTER_SCRIPT_INTERFACE

Effect bundle key, from the effect_bundles table.

Returns:

  1. CUSTOM_EFFECT_BUNDLE_SCRIPT_INTERFACE custom effect bundle

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1891

cm:apply_custom_effect_bundle_to_region(
  CUSTOM_EFFECT_BUNDLE_SCRIPT_INTERFACE effect bundle key,
  REGION_SCRIPT_INTERFACE effect bundle key
)
Apply a custom effect bundle to a region. Replaces any existing effect bundle with the same record.

Parameters:

1

CUSTOM_EFFECT_BUNDLE_SCRIPT_INTERFACE

Effect bundle key, from the effect_bundles table.

2

REGION_SCRIPT_INTERFACE

Effect bundle key, from the effect_bundles table.

Returns:

  1. CUSTOM_EFFECT_BUNDLE_SCRIPT_INTERFACE custom effect bundle

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1898

cm:apply_custom_effect_bundle_to_faction_province(
  CUSTOM_EFFECT_BUNDLE_SCRIPT_INTERFACE effect bundle key,
  REGION_SCRIPT_INTERFACE effect bundle key
)
Apply a custom effect bundle to a faction province. Replaces any existing effect bundle with the same record.

Parameters:

1

CUSTOM_EFFECT_BUNDLE_SCRIPT_INTERFACE

Effect bundle key, from the effect_bundles table.

2

REGION_SCRIPT_INTERFACE

Effect bundle key, from the effect_bundles table.

Returns:

  1. CUSTOM_EFFECT_BUNDLE_SCRIPT_INTERFACE custom effect bundle

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1905

Back to top

Diplomacy

cm:force_diplomacy_new(
  string source faction,
  string target faction,
  number bitmask,
  boolean can offer,
  boolean can accept
)

Disables or re-enables availability of a set of diplomacy types between factions described in the faction and target specifiers. Specifiers can be all, faction:<faction_key>, subculture:<subculture_key> or culture:<culture_key>.
The diplomacy types to be allowed or disallowed are specified with a bitmask. Diplomacy types can be included in the bitmask by adding the number corresponding to the diplomacy type to the mask value. This mapping is shown here:

Diplomacy TypeMask Value
trade agreement2^0
hard military access2^1
cancel hard military access2^2
military alliance2^3
regions2^4
technology2^5
state gift2^6
payments2^7
vassal2^8
peace2^9
war2^10
join war2^11
break trade2^12
break alliance2^13
hostages2^14
marriage2^15
non aggression pact2^16
soft military access2^17
cancel soft military access2^18
defensive alliance2^19
client state2^20
form confederation2^21
break non aggression pact2^22
break soft military access2^23
break defensive alliance2^24
break vassal2^25
break client state2^26
state gift unilateral2^27
The function campaign_manager:force_diplomacy on the campaign_manager interface wraps this function, providing a more useable interface and console output. It's recommended to call that function rather than directly calling this one.

Parameters:

1

string

Specifier that specifies one or more source factions.

2

string

Specifier that specifies one or more target factions.

3

number

Bitmask.

4

boolean

Sets whether the source faction(s) can to offer deals of this diplomacy type to the target faction(s).

5

boolean

Sets whether the target faction(s) can accept deals of this diplomacy type from the source faction(s).

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1922

cm:force_declare_war(
  string attacking faction key,
  string target faction key,
  boolean invite attacker allies,
  boolean invite defender allies,
  [boolean use command queue]
)

Forces one faction to declare war on another.

Parameters:

1

string

Faction key of the attacking faction, from the factions table.

2

string

Faction key of the target faction, from the factions table.

3

boolean

Allows factions allied with the attacker to choose whether to join.

4

boolean

Allows factions allied with the defender to choose whether to join.

5

boolean

optional, default value=true

Sends the declaration command via the command queue.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1962

cm:force_make_vassal(string vassalising faction key, string vassal faction key)

Force one faction to vassalise another faction.

Parameters:

1

string

Key of the faction which will become the master, from the factions table.

2

string

Key of the faction which will become the vassal, from the factions table.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1971

cm:force_alliance(string first faction key, string second faction key, boolean is military alliance)

Force two factions to become defensive or military allies.

Parameters:

1

string

Faction key of the first faction, from the factions table.

2

string

Faction key of the second faction, from the factions table.

3

boolean

Specifies whether the alliance should be a military alliance. If false is supplied then the alliance is defensive.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1977

cm:force_grant_military_access(
  string granting faction key,
  string recipient faction key,
  boolean is hard access
)

Force one faction to grant another faction military access to its territory.

Parameters:

1

string

Faction key of the granting faction, from the factions table.

2

string

Faction key of the recipient faction, from the factions table.

3

boolean

Indicates whether this should be hard military access. This concept is currently unused.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1984

cm:force_make_peace(string first faction key, string second faction key)

Forces peace between two warring factions.

Parameters:

1

string

Faction key of the first faction, from the factions table.

2

string

Faction key of the second faction, from the factions table.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1991

cm:force_confederation(string proposing faction key, string target faction key)

Forces a proposing faction to subsume a target faction into its confederation.

Parameters:

1

string

Faction key of the proposing faction, from the factions table.

2

string

Faction key of the target faction, from the factions table. This faction will be subsumed into the confederation.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 1997

cm:force_make_trade_agreement(string first faction key, string second faction key)

Forces a trade agreement between two specified factions. If no agreement is possible then nothing will happen.

Parameters:

1

string

Faction key of the first faction, from the factions table.

2

string

Faction key of the second faction, from the factions table.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2003

cm:make_diplomacy_available(string first faction key, string second faction key)

Makes diplomacy available between two factions, as if they had discovered each other on the campaign map.

Parameters:

1

string

Faction key of the first faction, from the factions table.

2

string

Faction key of the second faction, from the factions table.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2009

cm:faction_offers_peace_to_other_faction(string proposing faction key, string target faction key)

Compels one faction to offer peace to another faction that it's at war with. The target faction may decline.

Parameters:

1

string

Faction key of the first faction, from the factions table.

2

string

Faction key of the second faction, from the factions table.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2015

cm:steal_barter_agreement(
  string originator_faction_key,
  string target_faction_key,
  string steal_faction_key,
  number barter_agreement_index
)
Steal barter agreement of other two factions

Parameters:

1

string

originator_faction_key

2

string

target_faction_key

3

string

steal_faction_key

4

number

barter_agreement_index

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2021

cm:cancel_barter_agreement(
  string originator_faction_key,
  string target_faction_key,
  number barter_agreement_index
)
Break barter agreement between two factions

Parameters:

1

string

originator_faction_key

2

string

target_faction_key

3

number

barter_agreement_index

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2028

Back to top

Restrictions

cm:add_event_restricted_unit_record(string unit key, [string tooltip key])

Adds a restriction preventing a specified unit from being a recruitment option for any faction.
This setting is saved into the campaign save file when the game is saved, and automatically re-established when the campaign is reloaded.

Parameters:

1

string

Unit key, from the main_units table.

2

string

optional, default value=nil] string tooltip key, Key of localised text in full [table]_[field]_[key

Key of localised text in full [table]_[field]_[key] format to show as a tooltip on the restricted unit icon. This can be omitted.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2040

cm:remove_event_restricted_unit_record(string unit key)

Removes a restriction previously added with cm:add_event_restricted_unit_record.

Parameters:

1

string

Unit key, from the main_units table.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2047

cm:add_event_restricted_unit_record_for_faction(string unit key, string faction key, [string tooltip key])

Adds a restriction preventing a specified unit from being a recruitment option for a specified faction.
This setting is saved into the campaign save file when the game is saved, and automatically re-established when the campaign is reloaded.

Parameters:

1

string

Unit key, from the main_units table.

2

string

Faction key, from the factions table.

3

string

optional, default value=nil] string tooltip key, Key of localised text in full [table]_[field]_[key

Key of localised text in full [table]_[field]_[key] format to show as a tooltip on the restricted unit icon. This can be omitted.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2052

cm:remove_event_restricted_unit_record_for_faction(string unit key, string faction key)

Removes a restriction previously added with cm:add_event_restricted_unit_record_for_faction.

Parameters:

1

string

Unit key, from the main_units table.

2

string

Faction key, from the factions table.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2060

cm:add_event_restricted_building_record(string building key, [string tooltip key])

Adds a restriction preventing a specified building from being a construction option for any faction.
This setting is saved into the campaign save file when the game is saved, and automatically re-established when the campaign is reloaded.

Parameters:

1

string

Building key, from the building_levels table.

2

string

optional, default value=nil] string tooltip key, Key of localised text in full [table]_[field]_[key

Key of localised text in full [table]_[field]_[key] format to show as a tooltip on the restricted building icon. This can be omitted.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2066

cm:remove_event_restricted_building_record(string building key)

Removes a restriction previously added with cm:add_event_restricted_building_record.

Parameters:

1

string

Building key, from the building_levels table.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2073

cm:add_event_restricted_building_record_for_faction(
  string building key,
  string faction key,
  [string tooltip key]
)

Adds a restriction preventing a specified building from being a construction option for a specified faction.
This setting is saved into the campaign save file when the game is saved, and automatically re-established when the campaign is reloaded.

Parameters:

1

string

Building key, from the building_levels table.

2

string

Faction key, from the factions table.

3

string

optional, default value=nil] string tooltip key, Key of localised text in full [table]_[field]_[key

Key of localised text in full [table]_[field]_[key] format to show as a tooltip on the restricted building icon. This can be omitted.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2078

cm:remove_event_restricted_building_record_for_faction(string building key, string faction key)

Removes a restriction previously added with cm:add_event_restricted_building_record_for_faction.

Parameters:

1

string

Building key, from the building_levels table.

2

string

Faction key, from the factions table.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2086

cm:lock_technology(string faction key, string technology key)

Lock a specified technology and all technologies that are children of it, for a specified faction.
This setting is saved into the campaign save file when the game is saved, and automatically re-established when the campaign is reloaded.

Parameters:

1

string

Faction key, from the factions table.

2

string

Technology key, from the technologies table.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2092

cm:unlock_technology(string faction key, string technology key)

Removes a lock previously placed with cm:lock_technology.

Parameters:

1

string

Faction key, from the factions table.

2

string

Technology key, from the technologies table.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2099

cm:instantly_complete_ongoing_research_for_faction(
  string faction key,
  [boolean should_only_first_ongoing_research]
)

Instantly complete the ongoing research for given faction

Parameters:

1

string

Faction key, from the factions table.

2

boolean

optional, default value=false

If true, it will complete only the first ongoing research.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2104

cm:disable_movement_for_character(string character lookup)

Prevents the specified character from moving, regardless of where the move order comes from, until movement is subsequently re-enabled with cm:enable_movement_for_faction or cm:enable_movement_for_character.
This setting is saved into the campaign save file when the game is saved, and automatically re-established when the campaign is reloaded.

Parameters:

1

string

Character lookup string - see Character Lookups for more information.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2110

cm:disable_movement_for_faction(string faction key)

Prevents all characters in the specified faction from moving, regardless of where the move order comes from, until movement is subsequently re-enabled with cm:enable_movement_for_faction or cm:enable_movement_for_character. Note that characters created in the faction after this restriction is applied will not have this restriction applied and will be able to move.
This setting is saved into the campaign save file when the game is saved, and automatically re-established when the campaign is reloaded.

Parameters:

1

string

Faction key, from the factions table.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2116

cm:enable_movement_for_character(string character lookup)

Re-enables movement for a specified character after it has been disabled with cm:disable_movement_for_character or cm:disable_movement_for_faction.

Parameters:

1

string

Character lookup string - see Character Lookups for more information.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2122

cm:enable_movement_for_faction(string faction key)

Re-enables movement for every character in the specified faction after it has been disabled with cm:disable_movement_for_character or cm:disable_movement_for_faction.

Parameters:

1

string

Faction key, from the factions table.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2127

cm:disable_pathfinding_restriction(number id)

Disables a pathfinding restriction layer. These are layers that can be built into the campaign map data that prevent the player from being able to move into an area on the map. By calling this function to lift a restriction, the player will be able to pathfind into the new area.

Parameters:

1

number

Pathfinding restriction layer id to un-restrict. Layers are numbered sequentially - lifting the restriction on one layer will also lift it on all layers with a lower numerical id.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2132

cm:add_restricted_unit_upgrade(string source_unit_key, string target_unit_key)

Restricts the supplied unit by key from performing unit upgrade to the supplied unit by key.

Parameters:

1

string

Base unit to be upgraded.

2

string

Target unit to be upgraded to.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2137

cm:remove_restricted_unit_upgrade(string source_unit_key, string target_unit_key)

Re-enables the supplied unit by key to performing unit upgrade to the supplied unit by key, after it has been disabled with cm:add_restricted_unit_upgrade.

Parameters:

1

string

Base unit to be upgraded.

2

string

Target unit to be upgraded to.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2143

Back to top

Racial Mechanics

The functions described in this section affect racial mechanics that are generally specific to one or only a few races in the game. Avoid calling them for factions that aren't party to the racial mechanic in question.

cm:modify_faction_slaves_in_a_faction(string faction key, number change)

Modify the number of faction slaves in the specified faction. The change can be positive or negative. This function will only have an affect if the target faction makes use of the slaves mechanic.

Parameters:

1

string

Faction key, from the factions table.

2

number

Value to modify slaves by.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2153

cm:faction_economics_recalculate_background_income(string faction key)

Force a recalculation of the background income for the specified faction. This is done in order for the AI to know how much background income does it has.

Parameters:

1

string

Faction key, from the factions table.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2159

cm:province_spawn_pooled_resource(string province key, string resource key)

Spawn pooled_resource in province. Clamped to pool bounds.

Parameters:

1

string

Province key, from the provinces table.

2

string

Pooled resource key, from the pooled_resources table.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2164

cm:consume_pooled_resource(string province key, string resource key, number amount)

Consumes the specified pooled resource from the specified province, reducing the total amount avaliable in the deposit.

Parameters:

1

string

Province key, from the provinces table.

2

string

Pooled resource key, from the pooled_resources table.

3

number

Amount of resource to add. This value CANNOT be negative.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2170

cm:faction_add_pooled_resource(string faction key, string resource key, string factor key, number amount)

Add the specified amount to the specified resource pool (type of resource), as the specified factor (type of change). The supplied value will be clamped to pool and factor bounds.

Parameters:

1

string

Faction key, from the factions table.

2

string

Pooled resource key, from the pooled_resources table.

3

string

Change factor key, from the pooled_resource_factors table.

4

number

Amount of resource to add. This value can be negative.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2177

cm:faction_add_post_battle_looted_resource(
  string faction key,
  string resource key,
  string factor key,
  number amount
)

Add the specified amount to the specified pool for the loot in pending pattle participant. (must have active pending battle).

Parameters:

1

string

Faction key, from the factions table.

2

string

Pooled resource key, from the pooled_resources table.

3

string

Change factor key, from the pooled_resource_factors table.

4

number

Amount of resource to add. This value can be negative.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2185

cm:faction_add_post_battle_motivation_change(number character cqi, number amount)

Tells a pending battle object that there has been motivation changes to a character. Used to display to the user, doesn't actually change anything. Only works on characters in the currently pending battle.

Parameters:

1

number

Command queue index of the character whose motivation is changed

2

number

The amount of the change. Positive or negative value.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2193

cm:unlock_achievement(string faction_key , string achievement_key)

Unlocks achievement for faction.

Parameters:

1

string

faction_key

2

string

achievement_key

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2199

Back to top

Next Battle & Campaign

cm:add_custom_battlefield(
  string id,
  number x,
  number y,
  number radius,
  boolean dump campaign,
  string loading screen override,
  string script override,
  string whole battle override,
  number human alliance,
  boolean launch immediately,
  boolean is land battle,
  boolean force autoresolve result
)

Adds a record which modifies or completely overrides a battle involving the local player generated from campaign, if that battle happens within a certain supplied radius of a supplied campaign anchor position. Aspects of the battle may be specified, such as the loading screen and script to use, or the entire battle may be subsituted with an xml battle.

Parameters:

1

string

Id for this custom battle record. This may be used to later remove this override with cm:remove_custom_battlefield.

2

number

X logical co-ordinate of anchor position.

3

number

Y logical co-ordinate of anchor position.

4

number

Radius around anchor position. If a battle is launched within this radius of the anchor position and it involves the local player, then the battle is modified/overridden.

5

boolean

If set to true, the battle makes no attempt to load back into this campaign after completion.

6

string

Key of a custom loading screen to use, from the custom_loading_screens table. A blank string may be supplied to not override the loading screen. This is ignored if the entire battle is overriden with a battle xml, as that may specify a loading screen override.

7

string

Path to a script file to load with the battle, from the working data folder. A blank string may be supplied to not override the loading screen. This is ignored if the entire battle is overriden with a battle xml, as that may specify a script override.

8

string

Path to an battle xml file which overrides the whole battle.

9

number

Sets the index of the human alliance, 0 or 1, if setting a battle xml to override the whole battle. If not setting a battle xml this number is ignored.

10

boolean

Launch the battle immediately without saving the campaign first.

11

boolean

Sets whether the following battle is a land battle. This is only required if when launching the battle immediately.

12

boolean

If set to true, this forces the application of the autoresolver to the battle result after the battle, regardless of what happened in the battle itself. This is of most use for faking a battle result of an xml battle, which would otherwise return with no result.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2213

cm:remove_custom_battlefield(string id)

Removes a custom battle override previously set with cm:add_custom_battlefield.

Parameters:

1

string

id

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2229

cm:win_next_autoresolve_battle(string faction key)

The specified faction will win the next autoresolve battle.

Parameters:

1

string

Faction key, from the factions table.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2234

cm:modify_next_autoresolve_battle(
  number attacker win chance,
  number defender win chance,
  number attacker losses modifier,
  number defender losses modifier,
  boolean kill loser
)

Modifies the result of the next autoresolved battle.

Parameters:

1

number

Attacker win chance as a unary (0-1) value.

2

number

Defender win chance as a unary (0-1) value.

3

number

Multiplier for losses sustained by the attacker.

4

number

Multiplier for losses sustained by the defender.

5

boolean

Forces the loser of the battle to be wiped out if set to true.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2239

cm:override_attacker_win_chance_prediction(number chance)

Set the attackers predicted win chance percentage for the next battle, affecting the balance of power shown on the pre-battle screen. This will not change the result.
This function will only work if called while the pending battle is being set up.

Parameters:

1

number

Chance as a percentage, so a value of 50 would display a 50/50 attacker/defender balance.

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2248

cm:force_night_battle(string enable)

Forces the currently pending battle to be a night battle even if the general does not have the skill.

Parameters:

1

string

will force the battle to be a night battle if this is true

Returns:

  1. nil

defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2254

Back to top

AI

The functions in this section relate to campaign AI. Some functions allow blocking or promotion of strategic stances, which is a driver of how much an AI faction is predisposed to like another faction. Strategic stances may be specified by one of the following strings:

  • CAI_STRATEGIC_STANCE_BEST_FRIENDS

  • CAI_STRATEGIC_STANCE_VERY_FRIENDLY

  • CAI_STRATEGIC_STANCE_FRIENDLY

  • CAI_STRATEGIC_STANCE_NEUTRAL

  • CAI_STRATEGIC_STANCE_UNFRIENDLY

  • CAI_STRATEGIC_STANCE_VERY_UNFRIENDLY

  • CAI_STRATEGIC_STANCE_BITTER_ENEMIES
    • Stance by string
    CAI_STRATEGIC_STANCE_BEST_FRIENDS

    Strategic stances are different to, but loosely correlated with, the attitude score that is shown on the diplomacy screen. Generally speaking, diplomatic events (e.g. gifts, trespassing) lead to changes in attitude, which leads to changes in strategic stance, which leads to changes in behaviour. By setting two hostile factions to be best friends they will start being generally nicer to one another while still appearing to be hostile (although their attitude will likely improve over time due to positive events).

    cm:force_change_cai_faction_personality(string faction key, string personality key)

    Force the specified faction to adopt the specified AI personality.

    Parameters:

    1

    string

    Faction key, from the factions table.

    2

    string

    Personality key, from the cai_personalities table.

    Returns:

    1. nil

    defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2273

    cm:cai_strategic_stance_manager_block_all_stances_but_that_specified_towards_target_faction(
          string faction key,
      string     target faction key,
      string     strategic stance key
    )

    Sets one faction's stance towards another to the supplied strategic stance.

    Parameters:

    1

    string

    Faction key, from the factions table.

    2

    string

    Target faction key, from the factions table.

    3

    string

    Strategic stance key - see the list at the top of this section.

    Returns:

    1. nil

    defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2279

    cm:cai_strategic_stance_manager_promote_specified_stance_towards_target_faction(
          string faction key,
      string     target faction key,
      string     strategic stance key
    )

    Makes it much more likely that one faction's stance towards another will be the supplied strategic stance.

    Parameters:

    1

    string

    Faction key, from the factions table.

    2

    string

    Target faction key, from the factions table.

    3

    string

    Strategic stance key - see the list at the top of this section.

    Returns:

    1. nil

    defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2286

    cm:cai_force_personality_change(string faction key)

    Forces the specified faction to pick a new AI personality from their available pool. "All" may be supplied in place of a faction key to force all factions to change personalities.

    Parameters:

    1

    string

    Faction key, from the factions table, or "all".

    Returns:

    1. nil

    defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2293

    cm:cai_force_personality_change_with_override_round_number(string faction key, number round number)

    Within the ai personality assignment system it is possible to set up weightings between rounds and personalities, allowing for certain personalities to be more or less likely to be chosen depending on the turn number (so the AI changes behaviour over time). This command forces the specified faction to pick a new AI personality from their available pool, based on the supplied round number rather than the actual round number. "All" may be supplied in place of a faction key to force all factions to change personalities in this way.

    Parameters:

    1

    string

    Faction key, from the factions table, or "all".

    2

    number

    Override for turn/round number.

    Returns:

    1. nil

    defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2298

    cm:cai_strategic_stance_manager_force_stance_update_between_factions(
          string faction key,
      string     target faction key
    )

    Forces a stance update from one faction to another faction. The AI picks an appropriate new strategic stance.

    Parameters:

    1

    string

    Faction key, from the factions table.

    2

    string

    Target faction key, from the factions table.

    Returns:

    1. nil

    defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2304

    cm:cai_strategic_stance_manager_set_stance_promotion_between_factions_for_a_given_stance(
          string faction key,
      string     target faction key,
      string     strategic stance key,
      number     start round,
      number     start level,
      number     end round,
      number     end level
    )

    Sets up a process which promotes a particular strategic stance from one faction to a target faction over a number of turns.

    Parameters:

    1

    string

    Faction key, from the factions table.

    2

    string

    Target faction key, from the factions table.

    3

    string

    Strategic stance key - see the list at the top of this section.

    4

    number

    Starting round number.

    5

    number

    Starting stance level. This is a numerical indicator of how likely this stance is to be chosen.

    6

    number

    End round number.

    7

    number

    End stance level. This is a numerical indicator of how likely this stance is to be chosen.

    Returns:

    1. nil

    defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2310

    cm:cai_strategic_stance_manager_clear_all_promotions_between_factions(
          string faction key,
      string     target faction key
    )

    Clears any existing scripted stance promotions from one faction to a target faction.

    Parameters:

    1

    string

    Faction key, from the factions table.

    2

    string

    Target faction key, from the factions table.

    Returns:

    1. nil

    defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2321

    cm:cai_strategic_stance_manager_set_stance_blocking_between_factions_for_a_given_stance(
          string faction key,
      string     target faction key,
      string     strategic stance key,
      number     round number
    )

    Blocks a specific strategic stance from one faction to another faction until a specified round number.

    Parameters:

    1

    string

    Faction key, from the factions table.

    2

    string

    Target faction key, from the factions table.

    3

    string

    Strategic stance key - see the list at the top of this section.

    4

    number

    Final round number (inclusive) of blocking behaviour.

    Returns:

    1. nil

    defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2327

    cm:cai_strategic_stance_manager_clear_all_blocking_between_factions(
          string faction key,
      string     target faction key
    )

    Clears any existing scripted stance promotions between one faction and a target.

    Parameters:

    1

    string

    Faction key, from the factions table.

    2

    string

    Target faction key, from the factions table.

    Returns:

    1. nil

    defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2335

    cm:cai_disable_movement_for_character(string character lookup)

    Prevents the AI from being able to move a character. Other sources of character movement (e.g. the script or the player) will work as normal.

    Parameters:

    1

    string

    Character lookup string - see Character Lookups for more information.

    Returns:

    1. nil

    defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2341

    cm:cai_enable_movement_for_character(string character lookup)

    Allows the AI to move a character again after it was previously blocked with cm:cai_disable_movement_for_character.

    Parameters:

    1

    string

    Character lookup string - see Character Lookups for more information.

    Returns:

    1. nil

    defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2346

    cm:cai_disable_movement_for_faction(string faction key)

    Prevents the AI from being able to move any characters in a faction. Other sources of character movement (e.g. the script or the player) will work as normal.

    Parameters:

    1

    string

    Faction key, from the factions table.

    Returns:

    1. nil

    defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2351

    cm:cai_enable_movement_for_faction(string faction key)

    Allows the AI to move characters in a faction again after it was previously blocked with cm:cai_disable_movement_for_faction.

    Parameters:

    1

    string

    Faction key, from the factions table.

    Returns:

    1. nil

    defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2356

    cm:cai_disable_command_assignment_for_character(string character lookup)

    Prevents the AI from assigning the specified character to a position of command.

    Parameters:

    1

    string

    Character lookup string - see Character Lookups for more information.

    Returns:

    1. nil

    defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2361

    cm:cai_enable_command_assignment_for_character(string character lookup)

    Allows the AI to assigning the specified character to a position of command again after it was previously blocked with cm:cai_disable_command_assignment_for_character.

    Parameters:

    1

    string

    Character lookup string - see Character Lookups for more information.

    Returns:

    1. nil

    defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2366

    cm:cai_add_region_hint(FACTION_SCRIPT_INTERFACE faction, string region key)

    Adds a region to the VICTORY_CONDITION hint list of the faction.

    Parameters:

    1

    FACTION_SCRIPT_INTERFACE

    Faction for which the hint will be added.

    2

    string

    Region key for region to be added.

    Returns:

    1. nil

    defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2371

    cm:cai_remove_region_hint(FACTION_SCRIPT_INTERFACE faction, string region key)

    Removes a region from the VICTORY_CONDITION hint list of the faction, after it has previously been added via cm:cai_add_region_hint.

    Parameters:

    1

    FACTION_SCRIPT_INTERFACE

    Faction for which the hint will be added.

    2

    string

    Region key for region to be added.

    Returns:

    1. nil

    defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2376

    Back to top

    Audio

    The functions in this section relate to manipulating audio.

    cm:activate_music_trigger(string event)

    Triggers any valid Wwise event.

    Parameters:

    1

    string

    Wwise event key.

    Returns:

    1. nil

    defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2389

    cm:trigger_sound_event(string sound_event)

    Triggers any valid sound event by key.

    Parameters:

    1

    string

    Sound event key.

    Returns:

    1. nil

    defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2393

    cm:trigger_music_state(
          string music_faction,
      number     valid_timer,
      boolean     instant_change,
      [string     sound_event]
    )

    Triggers a change to music state.

    Parameters:

    1

    string

    Music faction key.

    2

    number

    Float timer.

    3

    boolean

    Instant change flag.

    4

    string

    optional, default value=false

    Optional sound event.

    Returns:

    1. nil

    defined in ../working_data/script/docgen/docgen_campaign_episodic_scripting.lua, line 2397

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