Episodic Scripting

The episodic scripting interface is one of the two main interface provided by the campaign model to script. Unlike the 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.

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 Empire faction at a display position [123,456]:

cm:force_add_trait("faction:wh_main_emp_empire,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 Greenskins:

local char_grn_faction_leader = cm:get_faction("wh_main_grn_greenskins"):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

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

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

Returns:

  1. userdata campaign model

cm:filesystem_lookup(string path)

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.

Parameters:

1

string

path

Returns:

  1. string file list

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

cm:is_dlc_flag_enabled(string dlc key)

Returns whether the dlc with the specified key is activated.

Parameters:

1

string

dlc key

Returns:

  1. dlc flag enabled
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

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.

cm:disable_saving_game(boolean should disable)

Prevents or allows the saving of the game.

Parameters:

1

boolean

should disable

Returns:

  1. nil

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

Returns:

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

cm:remove_time_trigger(string id)

Removes a time trigger by string id.

Parameters:

1

string

id

Returns:

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

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

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

Advisor and Audio

cm:dismiss_advice()
Dismisses the advisor panel.

Returns:

  1. nil

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

cm:trigger_campaign_vo(
  Triggers campaign voiceover audio at a character's 3D position. The character specified also partially specifies the path by which the voiceover sound is looked up.,
  string sound event,
  string character lookup,
  number delay
)

Parameters:

1

Triggers

campaign voiceover audio at a character's 3D position. The character specified also partially specifies the path by which the voiceover sound is looked up.

2

string

Sound event name.

3

string

Character lookup string - see Character Lookups for more information.

4

number

Delay in seconds before triggering the vo.

Returns:

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

cm:get_camera_position()
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.

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

cm:stop_camera()
Stops a scrolling camera.

Returns:

  1. nil

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

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

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

cm:cinematic()
Returns a cinematic script interface.

Returns:

  1. cinematics cinematic interface
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

cm:stop_user_input(boolean stop input)

Stops or allows user input.

Parameters:

1

boolean

stop input

Returns:

  1. nil

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

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

cm:enable_ui(boolean enable ui)

Enables or disables the user interface.

Parameters:

1

boolean

enable ui

Returns:

  1. nil

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

cm:spawn_agent_at_position(
  FACTION_SCRIPT_INTERFACE faction,
  number x,
  number y,
  string agent type,
  [string agent subtype]
)

Spawns an agent of the specified type at the specified logical position.
See the Model Hierarchy documentation for more information on the FACTION_SCRIPT_INTERFACE interface.

Parameters:

1

FACTION_SCRIPT_INTERFACE

Faction interface for the agent's faction.

2

number

x logical co-ordinate.

3

number

y logical co-ordinate.

4

string

Agent type key, from the agents table.

5

string

optional, default value=""

Agent subtype key, from the agent_subtypes table. This can be omitted.

Returns:

  1. nil

cm:spawn_agent_at_settlement(
  FACTION_SCRIPT_INTERFACE faction,
  SETTLEMENT_SCRIPT_INTERFACE settlement,
  string agent type,
  [string agent subtype]
)

Spawns an agent of the specified type next to the specified settlement.
See the Model Hierarchy documentation for more information on the FACTION_SCRIPT_INTERFACE or SETTLEMENT_SCRIPT_INTERFACE interfaces.

Parameters:

1

FACTION_SCRIPT_INTERFACE

Faction interface for the agent's faction.

2

SETTLEMENT_SCRIPT_INTERFACE

Settlement at which to spawn the agent.

3

string

Agent type key, from the agents table.

4

string

optional, default value=""

Agent subtype key, from the agent_subtypes table. This can be omitted.

Returns:

  1. nil

cm:spawn_agent_at_military_force(
  FACTION_SCRIPT_INTERFACE faction,
  MILITARY_FORCE_SCRIPT_INTERFACE force,
  string agent type,
  [string agent subtype]
)

Spawns an agent of the specified type next to the specified military force.
See the Model Hierarchy documentation for more information on the FACTION_SCRIPT_INTERFACE or MILITARY_FORCE_SCRIPT_INTERFACE interfaces.

Parameters:

1

FACTION_SCRIPT_INTERFACE

Faction interface for the agent's faction.

2

MILITARY_FORCE_SCRIPT_INTERFACE

Military force at which to spawn the agent.

3

string

Agent type key, from the agents table.

4

string

optional, default value=""

Agent subtype key, from the agent_subtypes table. This can be omitted.

Returns:

  1. nil

cm:embed_agent_in_force(CHARACTER_SCRIPT_INTERFACE agent, MILITARY_FORCE_SCRIPT_INTERFACE military force)
Instantly embed the specified agent in the specified force. The agent will teleport into the force, disregarding normal restrictions other than that force being under siege. See the Model Hierarchy documentation for more information on the CHARACTER_SCRIPT_INTERFACE or MILITARY_FORCE_SCRIPT_INTERFACE interfaces.

Parameters:

1

CHARACTER_SCRIPT_INTERFACE

agent

2

MILITARY_FORCE_SCRIPT_INTERFACE

military force

Returns:

  1. nil

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

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

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

cm:spawn_rogue_army(number x, number y)

Spawns a rogue army of a specified rogue army faction, at a specified position. This command will fail if the rogue army is already alive or is flagged to naturally spawn.
string faction key, Faction key, from the factions database table.

Parameters:

1

number

Logical x co-ordinate.

2

number

Logical y co-ordinate.

Returns:

  1. nil

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

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

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

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

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

cm:appoint_character_to_force(string character lookup, number mf cqi)

Appoints the specified character to the command of the specified military force. The character must be available (e.g. not dead or wounded, and not commanding another military force) for the appointment to work.

Parameters:

1

string

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

2

number

Command-queue index of the military force to appoint the character to.

Returns:

  1. nil

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

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

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

Character and Force 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

cm:add_agent_experience_through_family_member(FAMILY_MEMBER_SCRIPT_INTERFACE character, number points)

Adds experience points to a character specified by FAMILY_MEMBER_SCRIPT_INTERFACE. This interface is provided because if a character is in the process of dying, their FAMILY_MEMBER_SCRIPT_INTERFACE will exist where the CHARACTER_SCRIPT_INTERFACE may not.

Parameters:

1

FAMILY_MEMBER_SCRIPT_INTERFACE

FAMILY_MEMBER_SCRIPT_INTERFACE related to the character to apply experience points to.

2

number

Experience points to award.

Returns:

  1. nil

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

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

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

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

cm:move_to_queued(string character lookup, number x, number y)

Enqueues an order for the specified character to move to a specified logical position. This action will happen once the current action completes.

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.

Returns:

  1. nil

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

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

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

cm:leave_garrison(string character lookup, number x, number y)

Make the specified garrisoned character leave their garrison and move to a specified logical positon.

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.

Returns:

  1. nil

cm:attack(string character lookup, string target character lookup, boolean lay siege)

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

Instructs the character to lay siege to the target. This is useful if the target character is in a garrison.

Returns:

  1. nil

cm:attack_queued(string character lookup, string target character lookup, boolean lay siege)

Enqueues an order for the specified character to attack a target character. This action will happen once the current action completes.

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

Instructs the character to lay siege to the target. This is useful if the target character is in a garrison.

Returns:

  1. nil

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

cm:force_attack_of_opportunity(number attacker cqi, number target cqi, boolean is ambush)

Orders the specified character to attack a target character through an attack of opportunity - either an interception or an ambush. Note that this function requires character cqis to be passed in as arguments and not lookup strings.
The two characters must be of different factions that are at war and neither may be garrisoned for the action to succeed.

Parameters:

1

number

Command-queue index of the attacking character.

2

number

Command-queue index of the target character.

3

boolean

Set to true to ambush, or false to intercept.

Returns:

  1. nil

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

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

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

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

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

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

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

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

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

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

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

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

cm:stop_character_convalescing(number character cqi)

Instantly returns a convalescing (wounded) character to the available pool of recruitable characters for their faction.

Parameters:

1

number

character cqi

Returns:

  1. nil

cm:modify_character_personal_loyalty_factor(string character lookup, number loyalty modifier)

Modifies the loyalty of a specified character.

Parameters:

1

string

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

2

number

Amount to modify the loyalty by. This may be positive or negative.

Returns:

  1. nil

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

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

cm:convert_force_to_type(MILITARY_FORCE_SCRIPT_INTERFACE force, string type)

Converts a military force to a specific type. The military force is specified by MILITARY_FORCE_SCRIPT_INTERFACE - see the Model Hierarchy documentation for more information. The military force type is specified by string key, from the military_force_types database table.

Parameters:

1

MILITARY_FORCE_SCRIPT_INTERFACE

Military force.

2

string

Military force type, from the military_force_types table.

Returns:

  1. nil

cm:set_unit_hp_to_unary_of_maximum(UNIT_SCRIPT_INTERFACE unit, number unary hp)

Sets the hit points/number of men to the given unary proportion of the maximum for that unit. The unit is specified by UNIT_SCRIPT_INTERFACE - see the Model Hierarchy documentation for more information.

Parameters:

1

UNIT_SCRIPT_INTERFACE

Unit.

2

number

Unary proportion (0-1) of max hp value to set unit health to.

Returns:

  1. nil

cm:set_army_trespass_disabled(boolean should disable)

Globally disables or re-enables the penalties for army trespassing.

Parameters:

1

boolean

should disable

Returns:

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

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}
);

cm:remove_area_trigger(string trigger name)

Removes any area triggers established with cm:add_circle_area_trigger or cm:add_outline_area_trigger with the supplied name.

Parameters:

1

string

trigger name

Returns:

  1. nil

cm:add_hex_area_trigger(
  string trigger name,
  number x,
  number y,
  number radius,
  [string faction key],
  [string subculture key]
)

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

Parameters:

1

string

Unique name for this area trigger.

2

number

Logical x co-ordinate for the hex area.

3

number

Logical y co-ordinate for the hex area.

4

number

Radius in hexes (max of 20).

5

string

optional, default value=""

Key of faction to which the area trigger should apply, from the factions table. This may be a blank string if a subculture key is supplied.

6

string

optional, default value=""

Key of subculture to which the area trigger should apply, from the table. This may be a blank string if a subculture key is supplied.

Returns:

  1. nil

cm:remove_hex_area_trigger(string trigger name)

Removes any area triggers established with cm:add_hex_area_trigger with the supplied trigger name.

Parameters:

1

string

trigger name

Returns:

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

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

cm:force_add_ancillary(
  CHARACTER_SCRIPT_INTERFACE target_character,
  string ancillary key,
  boolean force equip,
  boolean suppress event feed
)

Grant the specified ancillary to the specified character.

Parameters:

1

CHARACTER_SCRIPT_INTERFACE

target_character

2

string

Ancillary key, from the ancillaries table.

3

boolean

if true the ancillary will be equipped and bypass any cooldowns or pre-conditions

4

boolean

if true no event feed events will be generated by this action

Returns:

  1. nil

cm:force_remove_ancillary(
  CHARACTER_SCRIPT_INTERFACE target_character,
  string ancillary key,
  boolean remove to pool,
  boolean suppress event feed
)

Remove the specified ancilliary from the specified character.

Parameters:

1

CHARACTER_SCRIPT_INTERFACE

target_character

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.

4

boolean

if true no event feed events will be generated by this action

Returns:

  1. nil

cm:add_ancillary_to_faction(
  FACTION_SCRIPT_INTERFACE target faction,
  string ancillary key,
  boolean suppress event feed
)

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

FACTION_SCRIPT_INTERFACE

target faction

2

string

Ancillary key, from the ancillaries table.

3

boolean

if true no event feed events will be generated by this action

Returns:

  1. nil

cm:force_remove_ancillary_from_faction(FACTION_SCRIPT_INTERFACE faction, string ancillary key)

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

Parameters:

1

FACTION_SCRIPT_INTERFACE

faction

2

string

Ancillary key, from the ancillaries table.

Returns:

  1. nil

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

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

Remove a skill point from the specified character and skill. Returns true if successful.

Parameters:

1

string

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

2

string

Skill key, from the character_skills table.

Returns:

  1. boolean skill point was removed

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

cm:remove_all_background_skills(string character lookup)

Forcibly remove all background skills for the specified character.

Parameters:

1

string

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

Returns:

  1. nil

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

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

Object Renaming

cm:change_localised_faction_name(string faction key, string name key)

Changes the name of a faction. The new name is specified by full localised text key, in the [table]_[key]_[field] format.

Parameters:

1

string

Faction key, from the factions table.

2

string

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

Returns:

  1. nil

cm:change_custom_faction_name(string faction key, string name)

Changes the name of a faction. The new name is specified directly as a string.

Parameters:

1

string

Faction key, from the factions table.

2

string

New name for the faction.

Returns:

  1. nil

cm:change_custom_settlement_name(SETTLEMENT_SCRIPT_INTERFACE settlement, string name key)

Changes the name of a settlement. The new name is specified by full localised text key, in the [table]_[key]_[field] format.

Parameters:

1

SETTLEMENT_SCRIPT_INTERFACE

Settlement object - see the Model Hierarchy documentation for more information about this interface.

2

string

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

Returns:

  1. nil

cm:change_localised_settlement_name(SETTLEMENT_SCRIPT_INTERFACE settlement, string name)

Changes the name of a faction. The new name is specified directly as a string.

Parameters:

1

SETTLEMENT_SCRIPT_INTERFACE

Settlement object - see the Model Hierarchy documentation for more information about this interface.

2

string

New name for the faction.

Returns:

  1. nil

cm:change_custom_region_name(REGION_SCRIPT_INTERFACE region, string name key)

Changes the name of a region. The new name is specified by full localised text key, in the [table]_[key]_[field] format. Note that the region name is not currently used for display - see cm:change_custom_settlement_name instead.

Parameters:

1

REGION_SCRIPT_INTERFACE

Region object - see the Model Hierarchy documentation for more information about this interface.

2

string

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

Returns:

  1. nil

cm:change_localised_region_name(REGION_SCRIPT_INTERFACE region, string name)

Changes the name of a region. The new name is specified directly as a string. Note that the region name is not currently used for display - see cm:change_localised_settlement_name instead.

Parameters:

1

REGION_SCRIPT_INTERFACE

Region object - see the Model Hierarchy documentation for more information about this interface.

2

string

New name for the region.

Returns:

  1. nil

cm:change_custom_unit_name(UNIT_SCRIPT_INTERFACE unit, string name key)

Changes the name of a unit. The new name is specified by full localised text key, in the [table]_[key]_[field] format.

Parameters:

1

UNIT_SCRIPT_INTERFACE

Unit object - see the Model Hierarchy documentation for more information about this interface.

2

string

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

Returns:

  1. nil

cm:change_localised_unit_name(UNIT_SCRIPT_INTERFACE unit, string name)

Changes the name of a unit. The new name is specified directly as a string.

Parameters:

1

UNIT_SCRIPT_INTERFACE

Unit object - see the Model Hierarchy documentation for more information about this interface.

2

string

New name for the unit.

Returns:

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

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

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

cm:disable_rebellions_worldwide(boolean disable)

Disables or re-enables all rebellions across the map.

Parameters:

1

boolean

disable

Returns:

  1. nil

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

cm:treasury_mod(string faction key, number amount)

Immediately modifies the treasury of the specified faction by the specified amount. The supplied value can be positive or negative.

Parameters:

1

string

Faction key, from the factions table.

2

number

Treasury modification.

Returns:

  1. nil

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

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

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

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

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

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

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

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.

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

cm:heal_garrison(number region cqi)

Heals the garrison army (and navy, where applicable) in the specified region back to full health. The region is specified by cqi.

Parameters:

1

number

Command-queue index of the target region.

Returns:

  1. nil

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

cm:force_religion_factors(
  string region key,
  string religion key,
  number religion proportion,
  ... extra religions
)

Forces the balance of religions in a specified province to specified values. The key of a region within the target province must be specified, along with one or more argument pairs specifying a religion key and a proportion for that religion. The sum of all specified religion proportions must equal 1. At least one religion/religion proportion pair of arguments must therefore be specified. Religions not specified in the arguments of this function call will not be present in the target province.
The religion system in Warhammer is repurposed to represent corruption. Use this function to override the setup of corruption within a province.
Note that this function will only work if called on turn one.

Parameters:

1

string

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

2

string

Key of a religion, from the religions table.

3

number

Unary proportion (0-1) of the religion specified by the previous argument. The unary proportion of all specified religions should add up to 1.

4

...

Extra religion key/religion proportion pairs of arguments, if desired.

Returns:

  1. nil

Example - Force a 60/40 untainted/undead corruption setup in Altdorf on turn one:

cm:force_religion_factors("wh_main_reikland_altdorf", "wh_main_religion_untainted", 0.6, "wh_main_religion_undeath", 0.40);

cm:add_unit_to_faction_mercenary_pool(
  FACTION_SCRIPT_INTERFACE faction,
  string unit,
  number count,
  number replenishment chance,
  number max units,
  number max per turn,
  number xp,
  string faction restriction,
  string subculture restriction,
  string tech restriction,
  boolean partial replenishment
)

Adds one or more units of a specified type to a faction's mercenary pool. These units can then be recruitable by that faction (or potentially other factions) using gameplay mechanics such as Regiments of Renown or Wulfhart's Mercenaries.

Parameters:

1

FACTION_SCRIPT_INTERFACE

Faction whose pool the unit(s) should be added to. For more information about the FACTION_SCRIPT_INTERFACE interface see the Model Hierarchy documentation.

2

string

Key of unit to add to the mercenary pool, from the main_units table.

3

number

Number of units to add to the mercenary pool.

4

number

Replenishment chance, as a percentage. This is the chance per-turn that the number of available units in the pool of the supplied type will be increased, if not already at its maximum.

5

number

The maximum number of units of the supplied type that the pool is allowed to contain.

6

number

The maximum number of units of the supplied type that may be added by replenishment per-turn.

7

number

The experience level of the units when recruited. This should be an integer value between 0-9.

8

string

The key of the faction who can actually recruit the units, from the factions database table. This may be different from the faction whose pool the unit is added to. An empty string "" may be supplied to omit this, which will usually be the case.

9

string

The key of the subculture who can actually recruit the units, from the cultures_subcultures database table. An empty string "" may be supplied to omit this, which will usually be the case.

10

string

The key of a technology that must be researched in order to recruit the units, from the technologies database table.

11

boolean

Allow replenishment of partial units.

Returns:

  1. nil

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. Unlike with cm:add_units_to_faction_mercenary_pool, the unit type must already be represented in the 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

cm:add_unit_to_province_mercenary_pool(
  REGION_SCRIPT_INTERFACE region,
  string unit,
  number count,
  number replenishment chance,
  number max units,
  number max per turn,
  number xp,
  string faction restriction,
  string subculture restriction,
  string tech restriction
)

Adds one or more units of a specified type to the mercenary pool in a province. These units can then be recruitable by that faction (or potentially other factions) using gameplay mechanics such as Raising Dead.

Parameters:

1

REGION_SCRIPT_INTERFACE

Region within the province to which the unit(s) should be added. For more information about the REGION_SCRIPT_INTERFACE interface see the Model Hierarchy documentation.

2

string

Key of unit to add to the mercenary pool, from the main_units table.

3

number

Number of units to add to the mercenary pool.

4

number

Replenishment chance, as a percentage. This is the chance per-turn that the number of available units in the pool of the supplied type will be increased, if not already at its maximum.

5

number

The maximum number of units of the supplied type that the pool is allowed to contain.

6

number

The maximum number of units of the supplied type that may be added by replenishment per-turn.

7

number

The experience level of the units when recruited. This should be an integer value between 0-9.

8

string

The key of the faction who can actually recruit the units, from the factions database table. This may be different from the faction whose pool the unit is added to. An empty string "" may be supplied to omit this, which will usually be the case.

9

string

The key of the subculture who can actually recruit the units, from the cultures_subcultures database table. An empty string "" may be supplied to omit this, which will usually be the case.

10

string

The key of a technology that must be researched in order to recruit the units, from the technologies database table.

Returns:

  1. nil

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. Unlike with cm:add_unit_to_province_mercenary_pool, the unit type must already be represented in the pool.

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

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

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

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

Cancels an active custom 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.

Returns:

  1. nil

cm:trigger_mission_with_targets(
  number faction cqi,
  string mission 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 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

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

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

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

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

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.

Returns:

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

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("wh_main_emp_empire", "wh_main_test_incident", true, "payload{money 1000;}");

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

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

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

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

cm:trigger_custom_dilemma_for_character(
  string character lookup,
  string dilemma key,
  string first choice payload,
  string second choice payload
)

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

Parameters:

1

string

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

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

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

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

cm:trigger_intrigue(
  string issuing faction,
  string faction a key,
  string faction b key,
  boolean improve,
  boolean exempt from cost
)

Triggers an intrigue (the High Elf game mechanic) incident which improves or worsens diplomatic relations between two supplied factions.

Parameters:

1

string

Key of the faction issuing the intrigue, from the factions database table.

2

string

Key of the first target faction, from the factions database table.

3

string

Key of the second target faction, from the factions database table.

4

boolean

Specifies that the intrigue should improve rather than worsen diplomatic relations between the target factions.

5

boolean

Specifies that the intrigue should not cost influence points for issuing faction.

Returns:

  1. nil
Back to top

Events and Suppression

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

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

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

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

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

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

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

Buildings and Slots

cm:region_slot_instantly_dismantle_building(SLOT_SCRIPT_INTERFACE slot)
Instantly dismantle the building in the supplied region slot. The slot is specified by SLOT_SCRIPT_INTERFACE - see the Model Hierarchy documentation for more information.

Parameters:

1

SLOT_SCRIPT_INTERFACE

slot

Returns:

  1. nil

cm:region_slot_instantly_upgrade_building(SLOT_SCRIPT_INTERFACE slot, string building key)

Instantly upgrade the building in the supplied region slot to the supplied building. The slot is specified by SLOT_SCRIPT_INTERFACE - see the Model Hierarchy documentation for more information. The building specified must be a valid upgrade for the building chain present in the slot.

Parameters:

1

SLOT_SCRIPT_INTERFACE

Slot script interface.

2

string

Building key, from the building_levels database table.

Returns:

  1. nil

cm:region_slot_instantly_repair_building(SLOT_SCRIPT_INTERFACE slot)
Instantly repair the building in the specified slot. Slots are specified by SLOT_SCRIPT_INTERFACE, see the Model Hierarchy documentation for more information.

Parameters:

1

SLOT_SCRIPT_INTERFACE

slot

Returns:

  1. nil

cm:foreign_slot_instantly_dismantle_building(number foreign slot cqi)

Instantly dismantles the building in the specified foreign slot. The slot is specified by slot cqi, which can be obtained from the foreign slot script interface on the model hierarchy.

Parameters:

1

number

foreign slot cqi

Returns:

  1. nil

cm:foreign_slot_instantly_upgrade_building(number foreign slot cqi, string building key)

Instantly upgrades the building in the specified foreign slot. The slot is specified by slot cqi, which can be obtained from the foreign slot script interface on the model hierarchy.

Parameters:

1

number

Foreign slot cqi.

2

string

Building key, from the building_levels table.

Returns:

  1. nil

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

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

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

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

cm:add_building_to_settlement(string region key, string building key, boolean operation was successful)

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

Parameters:

1

string

Key of the region containing the target settlement, from the campaign_map_regions table.

2

string

Building key, from the building_levels table.

3

boolean

operation was successful

Returns:

  1. nil

cm:add_foreign_slot_set_to_region_for_faction(number faction cqi, number region cqi, string slot set key)

Adds the specified foreign slot set to the target region, for the target faction. The foreign slot manager of the faction is returned, or a null script interface if parameters are invalid.

Parameters:

1

number

Command-queue index value of the target faction.

2

number

Command-queue index value of the target region.

3

string

Slot set key, from the slot_sets table.

Returns:

  1. FOREIGN_SLOT_MANAGER_SCRIPT_INTERFACE foreign slot manager

cm:instantly_set_settlement_primary_slot_level()
Instantly sets the primary slot level of the supplied settlement. The settlement is specified by SETTLEMENT_SCRIPT_INTERFACE - see the Model Hierarchy documentation for more information. The supplied level Will be clamped to the maximum level of the chain.
The new primary slot building will be returned, as a BUILDING_SCRIPT_INTERFACE object.

Returns:

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

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

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

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

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

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

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

Applies an effect bundle to a character. The character is specified by CHARACTER_SCRIPT_INTERFACE - see the Model Hierarchy documentation for more information.

Parameters:

1

string

Effect bundle key, from the effect_bundles table.

2

CHARACTER_SCRIPT_INTERFACE

Target character.

3

number

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

Returns:

  1. nil

cm:remove_effect_bundle_from_character(string effect bundle, CHARACTER_SCRIPT_INTERFACE character)

Removes an effect bundle from a character. The character is specified by CHARACTER_SCRIPT_INTERFACE - see the Model Hierarchy documentation for more information.

Parameters:

1

string

Effect bundle key, from the effect_bundles table.

2

CHARACTER_SCRIPT_INTERFACE

Target character.

Returns:

  1. nil

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

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

cm:apply_effect_bundle_to_faction_province(
  string effect bundle,
  REGION_SCRIPT_INTERFACE region,
  number turns
)

Applies an effect bundle to a province. The province is specified by REGION_SCRIPT_INTERFACE - see the Model Hierarchy documentation for more information. The effect bundle will be applied to the portion of the province owned by the owner of the specified region - this can be the whole province if one faction controls it all.

Parameters:

1

string

Effect bundle key, from the effect_bundles table.

2

REGION_SCRIPT_INTERFACE

Target region.

3

number

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

Returns:

  1. nil

cm:remove_effect_bundle_from_faction_province(string effect bundle, REGION_SCRIPT_INTERFACE region)

Removes an effect bundle from a province. The province is specified by REGION_SCRIPT_INTERFACE - see the Model Hierarchy documentation for more information. The effect bundle will be removed from the portion of the province owned by the owner of the specified region - this can be the whole province if one faction controls it all.

Parameters:

1

string

Effect bundle key, from the effect_bundles table.

2

REGION_SCRIPT_INTERFACE

Target region.

Returns:

  1. nil
Back to top

Custom Effect Bundles

Custom effect bundles may be created, customised, and then applied them to factions, regions, characters etc. While CUSTOM_EFFECT_BUNDLE_SCRIPT_INTERFACE objects may be created and applied using the functions listed here, the interface to customise them is described in the Model Hierarchy documentation.

cm:create_new_custom_effect_bundle(string base effect bundle)

Creates a new custom effect bundle, using the specified effect bundle record as a base. The custom effect bundle is returned as a CUSTOM_EFFECT_BUNDLE_SCRIPT_INTERFACE - see the Model Hierarchy documentation for more information.

Parameters:

1

string

Base effect bundle key, from the effect_bundles table.

Returns:

  1. CUSTOM_EFFECT_BUNDLE_SCRIPT_INTERFACE custom effect bundle

cm:apply_custom_effect_bundle_to_region(
  CUSTOM_EFFECT_BUNDLE_SCRIPT_INTERFACE custom effect bundle,
  REGION_SCRIPT_INTERFACE region
)
Applies a custom effect bundle to a region. This replaces any existing effect bundle with the same record.
For more information about the CUSTOM_EFFECT_BUNDLE_SCRIPT_INTERFACE or REGION_SCRIPT_INTERFACE interfaces see the Model Hierarchy documentation.

Parameters:

1

CUSTOM_EFFECT_BUNDLE_SCRIPT_INTERFACE

custom effect bundle

2

REGION_SCRIPT_INTERFACE

region

Returns:

  1. nil

cm:apply_custom_effect_bundle_to_faction(
  CUSTOM_EFFECT_BUNDLE_SCRIPT_INTERFACE custom effect bundle,
  FACTION_SCRIPT_INTERFACE faction
)
Applies a custom effect bundle to a faction. This replaces any existing effect bundle with the same record.
For more information about the CUSTOM_EFFECT_BUNDLE_SCRIPT_INTERFACE or FACTION_SCRIPT_INTERFACE interfaces see the Model Hierarchy documentation.

Parameters:

1

CUSTOM_EFFECT_BUNDLE_SCRIPT_INTERFACE

custom effect bundle

2

FACTION_SCRIPT_INTERFACE

faction

Returns:

  1. nil

cm:apply_custom_effect_bundle_to_character(
  CUSTOM_EFFECT_BUNDLE_SCRIPT_INTERFACE custom effect bundle,
  CHARACTER_SCRIPT_INTERFACE character
)
Applies a custom effect bundle to a character. This replaces any existing effect bundle with the same record.
For more information about the CUSTOM_EFFECT_BUNDLE_SCRIPT_INTERFACE or CHARACTER_SCRIPT_INTERFACE interfaces see the Model Hierarchy documentation.

Parameters:

1

CUSTOM_EFFECT_BUNDLE_SCRIPT_INTERFACE

custom effect bundle

2

CHARACTER_SCRIPT_INTERFACE

character

Returns:

  1. nil

cm:apply_custom_effect_bundle_to_force(
  CUSTOM_EFFECT_BUNDLE_SCRIPT_INTERFACE custom effect bundle,
  MILITARY_FORCE_SCRIPT_INTERFACE military force
)
Applies a custom effect bundle to a military force. This replaces any existing effect bundle with the same record.
For more information about the CUSTOM_EFFECT_BUNDLE_SCRIPT_INTERFACE or MILITARY_FORCE_SCRIPT_INTERFACE interfaces see the Model Hierarchy documentation.

Parameters:

1

CUSTOM_EFFECT_BUNDLE_SCRIPT_INTERFACE

custom effect bundle

2

MILITARY_FORCE_SCRIPT_INTERFACE

military force

Returns:

  1. nil

cm:apply_custom_effect_bundle_to_faction_province(
  CUSTOM_EFFECT_BUNDLE_SCRIPT_INTERFACE custom effect bundle,
  REGION_SCRIPT_INTERFACE region
)
Applies a custom effect bundle to a province. This replaces any existing effect bundle with the same record. The effect bundle will be applied to the portion of the province owned by the owner of the specified region - this can be the whole province if one faction controls it all.
For more information about the CUSTOM_EFFECT_BUNDLE_SCRIPT_INTERFACE or REGION_SCRIPT_INTERFACE interfaces see the Model Hierarchy documentation.

Parameters:

1

CUSTOM_EFFECT_BUNDLE_SCRIPT_INTERFACE

custom effect bundle

2

REGION_SCRIPT_INTERFACE

region

Returns:

  1. nil

cm:apply_custom_effect_bundle_to_characters_force(
  CUSTOM_EFFECT_BUNDLE_SCRIPT_INTERFACE custom effect bundle,
  CHARACTER_SCRIPT_INTERFACE character
)
Applies a custom effect bundle to a character's military force. This replaces any existing effect bundle with the same record.
For more information about the CUSTOM_EFFECT_BUNDLE_SCRIPT_INTERFACE or CHARACTER_SCRIPT_INTERFACE interfaces see the Model Hierarchy documentation.

Parameters:

1

CUSTOM_EFFECT_BUNDLE_SCRIPT_INTERFACE

custom effect bundle

2

CHARACTER_SCRIPT_INTERFACE

character

Returns:

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

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

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

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

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

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

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

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

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

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

cm:apply_dilemma_diplomatic_bonus(string faction a key, string faction a key, number bonus value)

Directly applies a diplomatic bonus or penalty between two factions, as if it had come from a dilemma. The bonus should be an integer between -6 and +6, each integer value of which corresponds to a change type (from PENALTY_XXXLARGE (-6) to BONUS_XXXLARGE (+6)) which carries a diplomatic attitude modifier that is actually applied.

Parameters:

1

string

First faction key.

2

string

Second faction key.

3

number

Bonus value (-6 to +6).

Returns:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

cm:modify_faction_slaves_in_a_faction_province(string region key, number change)

Modify the number of faction slaves in the province containing a specified region. 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

Region key, from the campaign_map_regions table.

2

number

Value to modify slaves by.

Returns:

  1. nil

cm:faction_set_food_factor_multiplier(string faction key, string food factor key, number multiplier)

Sets the multiplier of a scripted food type for a specified faction. The amount of food of this type this faction will earn per-turn will be multiplied by this amount.

Parameters:

1

string

Faction key, from the factions table.

2

string

Food factor key, from the food_factors table.

3

number

Multiplier.

Returns:

  1. nil

cm:faction_set_food_factor_value(string faction key, string food factor key, number modifier)

Sets the per-turn modifier of a scripted food type for a specified faction. This is the amount of food of this type this faction will earn per-turn.

Parameters:

1

string

Faction key, from the factions table.

2

string

Food factor key, from the food_factors table.

3

number

Modifier.

Returns:

  1. nil

cm:faction_mod_food_factor_value(string faction key, string food factor key, number modifier)

Modifies the per-turn modifier of a scripted food type for a specified faction. This is the amount of food of this type this faction will earn per-turn.
The supplied value is added to the existing modifier value.

Parameters:

1

string

Faction key, from the factions table.

2

string

Food factor key, from the food_factors table.

3

number

Modifier.

Returns:

  1. nil

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

cm:perform_ritual(string performing faction key, string target faction key, string ritual key)

Perform a ritual for a faction. The ritual must be available and valid for the action to succeed.

Parameters:

1

string

Faction key of the faction performing the ritual, from the factions table.

2

string

Faction key of the target faction of the ritual, from the factions table. An empty string may be supplied, in which case the performing faction is the target.

3

string

Ritual key, from the rituals table.

Returns:

  1. nil

cm:create_new_ritual_setup(FACTION_SCRIPT_INTERFACE performing faction, string ritual key)

Creates and returns a new MODIFY_RITUAL_SETUP_SCRIPT_INTERFACE, related to a ritual record from the database. This can be then be used to query, modify and trigger a ritual in script.

Parameters:

1

FACTION_SCRIPT_INTERFACE

Faction to perform the ritual.

2

string

Ritual key, from the rituals table.

Returns:

  1. nil

cm:perform_ritual_with_setup(RITUAL_SETUP_SCRIPT_INTERFACE interface ritual setup)
Perform a ritual with the provided setup. It must be available and valid for this call to succeed. Both modify and standard ritual setup interfaces are valid for this method

Parameters:

1

RITUAL_SETUP_SCRIPT_INTERFACE

Ritual setup to use. This can be either a RITUAL_SETUP_SCRIPT_INTERFACE or a MODIFY_RITUAL_SETUP_SCRIPT_INTERFACE object.

Returns:

  1. nil

cm:rollback_linked_ritual_chain(string ritual chain key, number stage)

Rolls back a linked ritual chain to the specified stage. It is safe to call this function if the ritual chain isn't at this stage yet.

Parameters:

1

string

Ritual chain key, from the campaign_group_ritual_chains table.

2

number

Stage number.

Returns:

  1. nil

cm:lock_ritual(FACTION_SCRIPT_INTERFACE faction, string ritual key)

Lock a ritual for a faction.

Parameters:

1

FACTION_SCRIPT_INTERFACE

Target faction.

2

string

Ritual key, from the rituals table.

Returns:

  1. nil

cm:unlock_ritual(FACTION_SCRIPT_INTERFACE faction, string ritual key, number duration)

Unlock a ritual for a faction.

Parameters:

1

FACTION_SCRIPT_INTERFACE

Target faction.

2

string

Ritual key, from the rituals table.

3

number

Duration, number of rounds the ritual will be unlocked for. Zero or negative will be infinite.

Returns:

  1. nil

cm:lock_ritual_chain(FACTION_SCRIPT_INTERFACE faction, string ritual_chain_key)

Lock a ritual chain for a faction.

Parameters:

1

FACTION_SCRIPT_INTERFACE

Target faction.

2

string

Ritual chain key, from the ritual_chains table.

Returns:

  1. nil

cm:unlock_ritual_chain(FACTION_SCRIPT_INTERFACE faction, string ritual chain key, number duration)

Unlock a ritual chain for a faction.

Parameters:

1

FACTION_SCRIPT_INTERFACE

Target faction.

2

string

Ritual Chain key, from the ritual_chains table.

3

number

Duration, number of rounds the ritual chain will be unlocked for. Zero or negative will be infinite.

Returns:

  1. nil

cm:lock_rituals_in_category(FACTION_SCRIPT_INTERFACE faction, string ritual_category_key)

Lock all rituals in a category for a faction.

Parameters:

1

FACTION_SCRIPT_INTERFACE

Target faction.

2

string

Ritual category key, from the ritual_categories table.

Returns:

  1. nil

cm:unlock_rituals_in_category(
  FACTION_SCRIPT_INTERFACE faction,
  string ritual_category_key,
  number duration
)

Unlocks all rituals in a category for a faction.

Parameters:

1

FACTION_SCRIPT_INTERFACE

Target faction.

2

string

Ritual category key, from the ritual_categories table.

3

number

Duration, number of rounds the rituals in the category will be unlocked for. Zero or negative will be infinite.

Returns:

  1. nil

cm:apply_active_ritual(FACTION_SCRIPT_INTERFACE faction, ACTIVE_RITUAL_SCRIPT_INTERFACE ritual)
Applies the effect of a ritual that is active right now. This is used in conjunction with the delay_payload_application field of the rituals database table. Should this field be set for a ritual, then that ritual will not apply its payload effects when triggered until this function or cm:apply_active_rituals is called.
Calls to this function will not succeed if the ritual has not been actively triggered.

Parameters:

1

FACTION_SCRIPT_INTERFACE

Target faction.

2

ACTIVE_RITUAL_SCRIPT_INTERFACE

Target ritual.

Returns:

  1. nil

cm:apply_active_rituals(FACTION_SCRIPT_INTERFACE faction)
Applies the effect of all rituals that are active for a faction right now. This is used in conjunction with the delay_payload_application field of the rituals database table. Should this field be set for a ritual, then that ritual will not apply its payload effects when triggered until this function or cm:apply_active_ritual is called.
Calls to this function will not succeed if the ritual has not been actively triggered.

Parameters:

1

FACTION_SCRIPT_INTERFACE

Target faction.

Returns:

  1. nil

cm:spawn_plague_at_settlement(SETTLEMENT_SCRIPT_INTERFACE settlement, string plague key)

Spawn a plague at a settlement.

Parameters:

1

SETTLEMENT_SCRIPT_INTERFACE

Target settlement.

2

string

Plague key, from the plagues table.

Returns:

  1. nil

cm:spawn_plague_at_region(REGION_SCRIPT_INTERFACE region, string plague key)

Spawn a plague in a region.

Parameters:

1

REGION_SCRIPT_INTERFACE

Target region.

2

string

Plague key, from the plagues table.

Returns:

  1. nil

cm:spawn_plague_at_military_force(MILITARY_FORCE_SCRIPT_INTERFACE military force, string plague key)

Spawn a plague at a military force.

Parameters:

1

MILITARY_FORCE_SCRIPT_INTERFACE

Target military force.

2

string

Plague key, from the plagues table.

Returns:

  1. nil

cm:faction_set_unit_purchasable_effect_availability(
  string faction key,
  string purchasable effect key,
  boolean available
)

Sets a unit purchasable effect to be available or unavailable for a specified faction. Unit purchasable effects are upgrades for units, which is supported for some factions/races.

Parameters:

1

string

Key of the target faction, from the factions database table.

2

string

Key of the purchasable effect, from the unit_purchasable_effects database table.

3

boolean

Sets whether the purchasable effect should be available or not.

Returns:

  1. nil

cm:faction_purchase_unit_effect(
  FACTION_SCRIPT_INTERFACE faction,
  UNIT_SCRIPT_INTERFACE unit,
  UNIT_PURCHASABLE_EFFECT_SCRIPT_INTERFACE purchasable effect
)
Makes the supplied faction purchase a supplied effect for a supplied unit. All arguments are specified by model hierarchy objects - see the Model Hierarchy documentation for more information.

Parameters:

1

FACTION_SCRIPT_INTERFACE

faction

2

UNIT_SCRIPT_INTERFACE

unit

3

UNIT_PURCHASABLE_EFFECT_SCRIPT_INTERFACE

purchasable effect

Returns:

  1. nil

cm:faction_set_unit_purchasable_effect_lock_state(
  FACTION_SCRIPT_INTERFACE faction,
  string purchasable effect,
  string lock reason,
  boolean should lock
)

Locks or unlocks the purchasable unit effect faction-wide, with an optional lock reason record. The purchasable effect is specified by string key. The faction is specified by FACTION_SCRIPT_INTERFACE - see the Model Hierarchy documentation for more information.

Parameters:

1

FACTION_SCRIPT_INTERFACE

Faction object.

2

string

Unit purchasable effect. This should be a key from the unit_purchasable_effects database table.

3

string

Lock reason. This should be a key from the unit_purchasable_effect_lock_reasons database table. A blank string may be supplied to not provide a lock reason.

4

boolean

Should lock - supply true to lock the effect, and false to unlock it.

Returns:

  1. nil

cm:faction_imprison_character(
  FACTION_SCRIPT_INTERFACE imprisoning faction,
  CHARACTER_SCRIPT_INTERFACE imprisoned character
)
Puts the supplied character into the supplied faction's prison. The faction and character are specified by model hierarchy objects - see the Model Hierarchy documentation for more information.

Parameters:

1

FACTION_SCRIPT_INTERFACE

imprisoning faction

2

CHARACTER_SCRIPT_INTERFACE

imprisoned character

Returns:

  1. nil

cm:faction_perform_action_on_prisoner(
  FACTION_SCRIPT_INTERFACE faction,
  FAMILY_MEMBER_SCRIPT_INTERFACE character,
  string action
)

Performs an action on a character within the faction's prison. The faction and character (family member) are specified by model hierarchy objects - see the Model Hierarchy documentation for more information.

Parameters:

1

FACTION_SCRIPT_INTERFACE

Imprisoning faction.

2

FAMILY_MEMBER_SCRIPT_INTERFACE

Imprisoned character - this is specified as a family member.

3

string

Action to perform. This should be a key from the campaign_prison_actions database table.

Returns:

  1. nil

cm:cook_recipe(FACTION_SCRIPT_INTERFACE faction, string recipe)

Attempt to cook a recipe for a faction. The default ingredients will be used.

Parameters:

1

FACTION_SCRIPT_INTERFACE

Faction object - see the Model Hierarchy documentation for more information.

2

string

Recipe to cook. This should be a key from the cooking_recipes database table.

Returns:

  1. boolean attempt was successful

cm:cook_recipe_with_ingredients(
  FACTION_SCRIPT_INTERFACE faction,
  string recipe,
  table primary ingredients,
  table secondary ingredients
)

Attempt to cook a recipe for a faction with the specified ingredients. The ingredients lists should be specified as tables of strings.

Parameters:

1

FACTION_SCRIPT_INTERFACE

Faction object - see the Model Hierarchy documentation for more information.

2

string

Recipe to cook. This should be a key from the cooking_recipes database table.

3

table

Table containing a list of string values. Each should be a key from the cooking_ingredients database table.

4

table

Table containing a list of string values. Each should be a key from the cooking_ingredients database table.

Returns:

  1. boolean attempt was successful

cm:force_cook_recipe(FACTION_SCRIPT_INTERFACE faction, string recipe, boolean apply cost)

Force a recipe to be cooked for a faction. The default ingredients will be used.

Parameters:

1

FACTION_SCRIPT_INTERFACE

Faction object - see the Model Hierarchy documentation for more information.

2

string

Recipe to cook. This should be a key from the cooking_recipes database table.

3

boolean

Apply the recipe cost.

Returns:

  1. boolean attempt was successful

cm:force_cook_recipe_with_ingredients(
  FACTION_SCRIPT_INTERFACE faction,
  string recipe,
  table primary ingredients,
  table secondary ingredients,
  boolean apply cost
)

Force a recipe to be cooked for a faction with the specified ingredients. The ingredients lists should be specified as tables of strings.

Parameters:

1

FACTION_SCRIPT_INTERFACE

Faction object - see the Model Hierarchy documentation for more information.

2

string

Recipe to cook. This should be a key from the cooking_recipes database table.

3

table

Table containing a list of string values. Each should be a key from the cooking_ingredients database table.

4

table

Table containing a list of string values. Each should be a key from the cooking_ingredients database table.

5

boolean

Apply the recipe cost.

Returns:

  1. boolean attempt was successful

cm:unlock_cooking_ingredient(FACTION_SCRIPT_INTERFACE faction, string ingredient)

Unlock an ingredient for a faction. The ingredient must be permitted for the faction.

Parameters:

1

FACTION_SCRIPT_INTERFACE

Faction object - see the Model Hierarchy documentation for more information.

2

string

Ingredient key, from the cooking_ingredients database table.

Returns:

  1. nil

cm:unlock_cooking_recipe(FACTION_SCRIPT_INTERFACE faction, string recipe)

Unlock a cooking recipe for a faction. The recipe must be permitted for the faction.

Parameters:

1

FACTION_SCRIPT_INTERFACE

Faction object - see the Model Hierarchy documentation for more information.

2

string

Recipe key, from the cooking_recipes database table.

Returns:

  1. nil

cm:clear_active_cooking_recipe(FACTION_SCRIPT_INTERFACE faction)
Clears the active recipe for the specified faction.

Parameters:

1

FACTION_SCRIPT_INTERFACE

Faction object - see the Model Hierarchy documentation for more information.

Returns:

  1. boolean recipe was cleared

cm:set_faction_max_primary_cooking_ingredients(FACTION_SCRIPT_INTERFACE faction, number max ingredients)

Sets the maximum number of primary ingredients that the specified faction may cook with. This value is clamped between 0 and 10.

Parameters:

1

FACTION_SCRIPT_INTERFACE

Faction object - see the Model Hierarchy documentation for more information.

2

number

Maximum number of ingredients.

Returns:

  1. nil

cm:set_faction_max_secondary_cooking_ingredients(
  FACTION_SCRIPT_INTERFACE faction,
  number max ingredients
)

Sets the maximum number of secondary ingredients that the specified faction may cook with. This value is clamped between 0 and 10.

Parameters:

1

FACTION_SCRIPT_INTERFACE

Faction object - see the Model Hierarchy documentation for more information.

2

number

Maximum number of ingredients.

Returns:

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

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

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

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

cm:skip_winds_of_magic_gambler(boolean should skip)

Sets whether the winds of magic gambler panel should be shown in the next player battle or not. The setting only affects the next battle.

Parameters:

1

boolean

should skip

Returns:

  1. nil

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

cm:pending_battle_add_scripted_tile_upgrade_tag(string tile upgrade key)

Adds the specified tile upgrade to the currently active pending battle. This should match the key of a tile upgrade set within the map data of the tile the battle will be fought on, so its use is highly situational.
The function will only work if called while the pending battle is being set up.

Parameters:

1

string

tile upgrade key

Returns:

  1. boolean upgrade was successful

cm:pending_battle_remove_scripted_tile_upgrade_tags(string tile upgrade key)

Removes the specified tile upgrade from the currently active pending battle. The function will only work if called while the pending battle is being set up.

Parameters:

1

string

tile upgrade key

Returns:

  1. boolean upgrade was successful
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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    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

    cm:cai_disable_targeting_against_settlement(string settlement key)

    Prevents any AI faction from targeting a specified settlement for capture for the rest of the campaign. This setting can be later cleared with cm:cai_enable_targeting_against_settlement.

    Parameters:

    1

    string

    Settlement key, from the campaign_map_settlements database table. This will be settlement: followed by the region key.

    Returns:

    1. nil

    cm:cai_enable_targeting_against_settlement(string settlement key)

    Clears any restriction previously set with cm:cai_disable_targeting_against_settlement, allowing AI factions to target a specified settlement for capture again.

    Parameters:

    1

    string

    Settlement key, from the campaign_map_settlements database table. This will be settlement: followed by the region key.

    Returns:

    1. nil
    Last updated 07/02/21 06:39:14