Episodic Scripting
The episodic scripting interface is one of the two main interface provided by the campaign model to script. Unlike the campaign model hierarchy, which is used to query the state of the model, the episodic scripting interface is primarily used to make changes to the model.
The original documentation for the episodic scripting interface can be found here: Episodic Scripting interface. Note that a campaign must be loaded to generate this documentation.
| Loaded in Campaign |
|
| Loaded in Battle |
|
| Loaded in Frontend |
|
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()
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 name | description |
|---|---|
faction | Faction key, from the factions table. |
type | Agent type, from the agent_types table. |
ability | Agent ability, from the abilities table. |
forename | Forename, from the names table. |
surname | Surname, from the names table. |
x | Display x co-ordinate - must be used in conjection with a y display co-ordinate and a radius. |
y | Display y co-ordinate - must be used in conjection with an x display co-ordinate and a radius. |
r | Radius around specified x/y display position. |
garrison | Settlement name of a garrison to look in, from the campaign_map_settlements table. |
character_cqi | The command queue index of a character. This is always unique. |
Should the filters specified in the character lookup string return more than one eligible character then only the first of these is used in the function call. Generally, it's a good idea to ensure that filters will only return one character, so it's strongly recommended to solely use the character_cqi filter which will only ever match one character.
A filter may be specified in the lookup string in the form <filter_name>:<filter_value>. Multiple filters may be specified in a lookup string, separated by a comma. Furthermore, the campaign manager function campaign_manager:char_lookup_str can also be used to convert a character object, or its cqi number, into a character lookup string.
Example - Add trait to a character from the Achilles faction at a display position [123,456]:
cm:force_add_trait("faction:troy_main_dan_achilles,x:123,y:456,r:1", "trait_general_good", true)
Example - Remove all action points from a character with cqi 45:
cm:zero_action_points("character_cqi:45")
Example - Use the char_lookup_str function to disable movement for the faction leader of the Aetolians:
local char_grn_faction_leader = cm:get_faction("troy_main_dan_aetolians"):faction_leader()
cm:disable_movement_for_character(cm:char_lookup_str(char_grn_faction_leader))
-
cm:is_new_game() -
Returns
trueif this a new campaign game, orfalseotherwise. A new game is one that has yet to be saved and reloaded.Returns:
boolean
-
cm:is_benchmark_mode() -
Returns
trueif this campaign is running in benchmark mode, meaning it was launched from the benchmark section in the graphics options.Returns:
boolean
-
cm:model() -
Returns a handle to the campaign model object.
Returns:
userdatacampaign model
-
cm:filesystem_lookup() -
Perform a VFS lookup in the specified path (root is the data folder) for files matching the pattern. Returns a comma-delimited list of files found.
Returns:
string
-
cm:compare_localised_string(uicomponentuicomponent,label stringstring) -
Returns whether the supplied label string matches the text of a supplied uicomponent, taking localisation into account.
Parameters:
1
uicomponent
2
label string
Returns:
boolean
-
cm:set_campaign_time_of_day(time of day valuenumber) -
Instantly sets the campaign time-of-day setting, by numeric value. Valid values are:
Value Description
0 Normal day/night cycle 1 Fast day/night cycle 2 Slow day/night cycle 3 Always morning 4 Always noon 5 Always evening 6 Always night 7 User's local time Parameters:
1
time of day value
Returns:
nil
-
cm:save_named_value(value namestring, datavalue to save, contextcontext object) -
Write a value to the savegame. This should only be called when the
SavingGameevent 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 theSaving Gamesection of this documentation, instead of directly calling this function.Parameters:
1
Value name.
2
data3
contextcontext object
Returns:
nil
-
cm:load_named_value(value namestring, datadefault value, contextcontext object) -
Reads a value from a loading game. Should only be called when the
LoadingGameevent 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 theLoading Gamesection of this documentation, instead of directly calling this function.Parameters:
1
Value name.
2
dataThis 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,numberorstring.3
contextcontext object
Returns:
-
cm:disable_saving_game(should disableboolean) -
Prevents or allows the saving of the game.
Parameters:
1
should disable
Returns:
nil
-
cm:is_saving_disabled() -
Returns whether saving has currently been disabled with
cm:disable_saving_game.Returns:
boolean
-
cm:save_game(filenamestring,file descriptionstring) -
Save the game with the supplied filename and optional description. The description is only used when saving multiplayer games. A boolean value is returned to indicate whether the operation succeeded - the save operation can fail if the game is in the wrong state, such as if a character is currently moving.
Parameters:
1
filename
2
file description
Returns:
boolean
-
cm:enable_start_turn_autosave(enableboolean) -
Enables or disables autosaving at the start of turn. By default, turn-start autosaving is enabled - use this function to disable it.
Parameters:
1
enable
Returns:
nil
-
cm:enable_legendary_mode_restrictions(should enableboolean) -
Enable/Disable legendary mode restrictions, such as manual saving, battle rematch, etc. This doesn't change game difficulty.
Parameters:
1
should enable
Returns:
nil
-
cm:autosave_at_next_opportunity() -
Autosave the game at the next opportunity.
Returns:
nil
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(idstring,intervalnumber, [repeatboolean]) -
Register a time trigger, in seconds. This will cause a
TimeTriggerevent to trigger after the specified interval.Parameters:
1
ID for this time trigger. This will be supplied with the
TimeTriggerevent when it is triggered.2
Interval after which to trigger the
TimeTriggerevent, in seconds.3
optional, default value=false
Repeats the time trigger if set to
true.Returns:
nil
-
cm:remove_time_trigger(idstring) -
Removes a time trigger by
stringid.Parameters:
1
id
Returns:
nil
-
cm:disable_end_turn(should disableboolean) -
Prevents or allows ending turn.
Parameters:
1
should disable
Returns:
nil
-
cm:end_turn() -
Ends the turn for the current faction.
Returns:
nil
-
cm:set_ai_uses_human_display_speed(use human speedboolean) -
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
use human speed
Returns:
nil
-
cm:dismiss_advice() -
Dismisses the advisor panel.
Returns:
nil
-
cm:dismiss_advice_at_end_turn(should dismissboolean) -
Set whether or not advice should be dismissed on ending turn.
Parameters:
1
should dismiss
Returns:
nil
-
cm:hide_advisor_without_infotexts() -
Hides the advisor panel, leaving the infotext panel opened
Returns:
nil
The functions in this section make use of camera co-ordinates. These are specified by five numeric components:
- display x co-ordinate of camera target
- display y co-ordinate of camera target
- horizontal distance from target to camera
- horizontal bearing in radians of target from camera
- height of camera
Example - scroll_camera_with_direction usage:
Example ofcm: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(xnumber,ynumber,dnumber,bnumber,hnumber) -
Repositions the camera to the specified co-ordinates.
Parameters:
1
Display x co-ordinate of camera target.
2
Display y co-ordinate of camera target.
3
Horizontal distance from camera to target.
4
Horizontal bearing in radians of target from camera.
5
Height of camera.
Returns:
nil
-
cm:get_camera_position() -
Returns the current position of the camera.
Returns:
-
cm:get_camera_position_cindy_format() -
Returns the current position of the camera in format xyz position, xyz target.
Returns:
numbernumbernumbernumbernumbernumber
-
cm:scroll_camera(adjust endpointboolean,scroll timenumber, varargco-ordinate list) -
Scroll the camera along a spline.
Parameters:
1
Adjust the endpoint to be valid for gameplay. Set this to
trueif control is to be restored to the player after this camera movement finishes. Set tofalseif another camera movement follows this one.2
Scroll time in seconds
3
varargVararg list of co-ordinates. Each co-ordinate must be specified in a
tablecontaining fournumberco-ordinate components.Returns:
nil
-
cm:scroll_camera_with_direction(adjust endpointboolean,scroll timenumber, varargco-ordinate list) -
Scroll the camera along a list of co-ordinates that define a spline.
Parameters:
1
Adjust the endpoint to be valid for gameplay. Set this to
trueif control is to be restored to the player after this camera movement finishes. Set tofalseif another camera movement follows this one.2
Scroll time in seconds
3
varargVararg list of co-ordinates. Each co-ordinate must be specified in a
tablecontaining fivenumberco-ordinate components.Returns:
nil
-
cm:stop_camera() -
Stops a scrolling camera.
Returns:
nil
-
cm:fade_scene(brightnessnumber,durationnumber) -
Fades the scene to black or back to picture over a specified period, starting from the current brightness.
Parameters:
1
Brightness, as a unary value. Supply a value of
0to fade to black, supply a value of1to fade to picture, or supply a value in between to transition to a partially-faded picture.2
Duration of the fade effect in seconds.
Returns:
nil
-
cm:register_instant_movie(movie pathstring) -
Plays a fullscreen movie, by path from the
data/Moviesdirectory.Parameters:
1
movie path
Returns:
nil
-
cm:register_outro_movie(movie pathstring) -
Plays a fullscreen movie for an outro, by path from the
data/Moviesdirectory. The campaign will exit once playback has completed.Parameters:
1
movie path
Returns:
nil
-
cm:play_movie_in_ui(movie pathstring) -
Plays a movie in the movie panel, by path from the
data/Moviesdirectory.Parameters:
1
movie path
Returns:
nil
-
cm:cinematic() -
Returns a cinematic script interface.
Returns:
cinematics
-
cm:override_ui(ui override namestring,activate overrideboolean) -
Activates or deactivates a ui override.
Parameters:
1
ui override name
2
activate override
Returns:
nil
-
cm:stop_user_input(stop inputboolean) -
Stops or allows user input.
Parameters:
1
stop input
Returns:
nil
-
cm:steal_user_input(steal inputboolean) -
Steals user input, so that input notifications are redirected to script. When keypresses are stolen by script the game calls a function called
OnKeyPressedwhen a keypress occurs. This function can be declared in script to receive these notifications.Parameters:
1
steal input
Returns:
nil
-
cm:steal_escape_key(steal escape keyboolean) -
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
OnKeyPressedwhen a keypress occurs. This function can be declared in script to receive these notifications.Parameters:
1
steal escape key
Returns:
nil
-
cm:enable_ui(enable uiboolean) -
Enables or disables the entire user interface.
Parameters:
1
enable ui
Returns:
nil
-
cm:disable_shortcut(component idstring,function idstring,should disableboolean) -
Disables or re-enables a shortcut by name. Shortcuts can be looked up in
data/text/default_keys.xml.Parameters:
1
Component id, specified by the
componentattibute of afuncelement.2
Function id, specified by the
nameattribute of afuncelement.3
Should disable.
Returns:
nil
-
cm:disable_all_shortcuts(disableboolean) -
Disable or enable all shortcuts.
Parameters:
1
disable
Returns:
nil
-
cm:add_unit_model_overrides(character lookupstring,model keystring) -
Swap a model for a certain character. This needs to be set up at a new session.
Parameters:
1
Character lookup string - see
Character Lookupsfor more information.2
model key
Returns:
nil
-
cm:add_character_model_override(charactercharacter,model keystring) -
Swap a model for a specific character. Same as add_unit_model_overrides, but doesn't use the character lookup.
Parameters:
1
Character interface.
2
Model key, from the
campaign_character_art_setsdatabase table.Returns:
nil
-
cm:highlight_movement_extents(should highlightboolean) -
Causes movement extents surrounded a selected character in the game to flash or not.
Parameters:
1
should highlight
Returns:
nil
-
cm:highlight_selected_character_zoc(should highlightboolean) -
Causes the zone of control surrounding a selected character in the game to flash or not.
Parameters:
1
should highlight
Returns:
nil
-
cm:set_exclusive_visible_labels(faction keystable) -
Sets a whitelist of factions whose labels should be visible on the campaign map. If a faction is not present in the whitelist then its labels will not be visible. If the whitelist is empty, then labels for all factions are visible.
Parameters:
1
Numerically-indexed table of faction keys.
Returns:
nil
-
cm:add_marker(marker idstring,marker typestring,xnumber,ynumber,heightnumber) -
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
Unique id for this marker, by which it may be later removed.
2
Marker type. Supported marker types are
move_to,select,pointer,move_to_vfx,select_vfx,look_at_vfxandobjective.3
x display position.
4
y display position.
5
height above water plane.
Returns:
nil
-
cm:remove_marker(marker idstring) -
Removes a marker previously added using
cm:add_marker, by marker id.Parameters:
1
marker id
Returns:
nil
-
cm:add_interactable_campaign_marker(unique id
string,marker info
string,x
number,y
number,radius
number,faction key
string,subculture key
string
) -
Add an interactable campaign marker of a specified type to the campaign map at a specified logical location. A radius around the marker is specified. As matching campaign characters enter or leave this radius then
AreaEntered/AreaExitedevents 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
Unique id for this campaign marker, by which it may be later removed with
cm:remove_interactable_campaign_marker.2
Marker info key. This should match a record from the
campaign_interactable_marker_infostable.3
Logical x position for the marker.
4
Logical y position for the marker.
5
Radius around the position at which to trigger
AreaEntered/AreaExitedevents.6
Faction key filter. A blank string can be supplied to omit this.
7
Subculture key filter. A blank string can be supplied to omit this.
Returns:
nil
-
cm:add_interactable_campaign_marker_by_real_world_position(unique id
string,marker info
string,x
number,y
number,height
number,use terrain height
number,radius
number,faction key
string,subculture key
string
) -
Add an interactable campaign marker of a specified type to the campaign map at a specified display location. A radius around the marker is specified. As matching campaign characters enter or leave this radius then
AreaEntered/AreaExitedevents will be triggered.Parameters:
1
Unique id for this campaign marker, by which it may be later removed with
cm:remove_interactable_campaign_marker.2
Marker info key. This should match a record from the
campaign_interactable_marker_infostable.3
Display x position for the marker.
4
Display y position for the marker.
5
Display height for the marker.
6
Use the terrain height for the marker.
7
Radius around the position at which to trigger
AreaEntered/AreaExitedevents.8
Faction key filter. A blank string can be supplied to omit this.
9
Subculture key filter. A blank string can be supplied to omit this.
Returns:
nil
-
cm:add_interactable_campaign_port_marker(marker id
string,marker info
string,x
number,y
number,radius
number,faction key
string,subculture key
string
) -
Adds an interactable campaign port marker to the campaign map at the specified logical location. A radius around the marker is specified. As matching campaign characters enter or leave this radius then
AreaEntered/AreaExitedevents will be triggered.Parameters:
1
Unique id for this marker, by which it may be later removed.
2
Marker info key, from the
campaign_interactable_marker_infosdatabase table.3
Logical x position for the marker.
4
Logical y position for the marker.
5
Radius around the position at which to trigger
AreaEntered/AreaExitedevents.6
Faction key filter. A blank string can be supplied to omit this.
7
Subculture key filter. A blank string can be supplied to omit this.
Returns:
nil
-
cm:add_blood_marker(id
string,info key
string,x
number,y
number,radius
number,faction key
string,subculture key
string,tooltip key
string
) -
Add an interactable campaign blood marker to the campaign map at a specified logical position. A radius around the marker is specified. As matching campaign characters enter or leave this radius then
AreaEntered/AreaExitedevents will be triggered.Parameters:
1
stringUnique marker id.
2
stringMarker info key, from the
campaign_interactable_marker_infosdatabase table.3
numberLogical position x.
4
numberLogical position y.
5
numberRadius.
6
Faction key, from the
factionsdatabase table. A blank string can be provided to not filter by faction.7
Subculture key from the
subculturesdatabase table.8
Tooltip key, in the full [table]_[field]_[key] localisation format.
Returns:
nil
-
cm:remove_interactable_campaign_marker(unique idstring) -
Removes an interactable campaign marker that was previously added with
cm:add_interactable_campaign_marker, by unique id.Parameters:
1
unique id
Returns:
nil
-
cm:add_vfx(vfx idstring,vfxstring,xnumber,ynumber,heightnumber) -
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
Unique id for this vfx, by which it may later be removed with
cm:remove_vfx.2
VFX type. This must be an entry from the
vfx_eventfield of thecampaign_vfx_lookupstable.3
x display position.
4
y display position.
5
height above water plane.
Returns:
nil
-
cm:remove_vfx(vfx idstring) -
Removes a vfx previously added with
cm:add_vfx, by vfx id.Parameters:
1
vfx id
Returns:
nil
-
cm:add_character_vfx(character cqi
number,vfx
string,show in shroud
boolean,show in fow
boolean,show on quad map
boolean
) -
Adds a vfx to a specified character.
Parameters:
1
Command queue index of the character.
2
VFX type. This must be an entry from the
vfx_eventfield of thecampaign_vfx_lookupstable.3
Show this vfx even when the character is under the shroud.
4
Show this vfx even when the character is under fog of war.
5
Show this vfx even when the camera zoom level is on the quad map only rendering.
Returns:
nil
-
cm:remove_character_vfx(character cqinumber,vfxstring) -
Removes a vfx from a specified character.
Parameters:
1
Command queue index of the character.
2
VFX type. This must be an entry from the
vfx_eventfield of thecampaign_vfx_lookupstable.Returns:
nil
-
cm:add_garrison_residence_vfx(garrison residence cqi
number,vfx
string,show in shroud
boolean,show in fow
boolean,show on quad map
boolean
) -
Adds a vfx to a specified garrison residence/settlement.
Parameters:
1
Command queue index of the garrison residence.
2
VFX type. This must be an entry from the
vfx_eventfield of thecampaign_vfx_lookupstable.3
Show this vfx even when the garrison residence is under the shroud.
4
Show this vfx even when the garrison residence is under fog of war.
5
Show this vfx even when the camera zoom level is on the quad map only rendering.
Returns:
nil
-
cm:remove_garrison_residence_vfx(character cqinumber,vfxstring) -
Removes a vfx from a specified character.
Parameters:
1
Command queue index of the character.
2
VFX type. This must be an entry from the
vfx_eventfield of thecampaign_vfx_lookupstable.Returns:
nil
-
cm:add_scripted_composite_scene_to_logical_position(name
string,composite scene
string,x
number,x
number,facing x
number,facing y
number,one shot
boolean,show in seen shroud
boolean,show in unseen shroud
boolean
) -
Adds a composite scene at a specified logical position.
Parameters:
1
Unique name for this composite scene, by which it may later be removed with
cm:remove_scripted_composite_scene.2
Composite scene key from the
campaign_composite_scenestable.3
Logical x co-ordinate.
4
Logical y co-ordinate.
5
Logical x co-ordinate of a position this composite scene faces.
6
Logical y co-ordinate of a position this composite scene faces.
7
One shot - if set to
true, this composite scene is not added to the internal list of scenes and can't later be removed withcm:remove_scripted_composite_scene. However, the name of one-shot scenes does not have to be unique.8
Sets whether this composite scene should be drawn when in thin shroud over previously-seen terrain.
9
Sets whether this composite scene should be drawn when in thick shroud over unseen terrain.
Returns:
boolean
-
cm:add_scripted_composite_scene_to_settlement(name
string,composite scene
string,settlement key
string,facing x
number,facing y
number,one shot
boolean,show in seen shroud
boolean,show in unseen shroud
boolean
) -
Adds a composite scene to a specified settlement.
Parameters:
1
Unique name for this composite scene, by which it may later be removed with
cm:remove_scripted_composite_scene.2
Composite scene key from the
campaign_composite_scenestable.3
Key of settlement to add the scene to, from the
campaign_map_settlementstable.4
Logical x co-ordinate of a position this composite scene faces.
5
Logical y co-ordinate of a position this composite scene faces.
6
One shot - if set to
true, this composite scene is not added to the internal list of scenes and can't later be removed withcm:remove_scripted_composite_scene. However, the name of one-shot scenes does not have to be unique.7
Sets whether this composite scene should be drawn when in thin shroud over previously-seen terrain.
8
Sets whether this composite scene should be drawn when in thick shroud over unseen terrain.
Returns:
boolean
-
cm:add_scripted_composite_scene_to_settlement_port(name
string,composite scene
string,settlement key
string,facing x
number,facing y
number,one shot
boolean,show in seen shroud
boolean,show in unseen shroud
boolean
) -
Adds a composite scene to the port slot of a specified settlement.
Parameters:
1
Unique name for this composite scene, by which it may later be removed with
cm:remove_scripted_composite_scene.2
Composite scene key from the
campaign_composite_scenestable.3
Key of settlement to add the scene to, from the
campaign_map_settlementstable.4
Logical x co-ordinate of a position this composite scene faces.
5
Logical y co-ordinate of a position this composite scene faces.
6
One shot - if set to
true, this composite scene is not added to the internal list of scenes and can't later be removed withcm:remove_scripted_composite_scene. However, the name of one-shot scenes does not have to be unique.7
Sets whether this composite scene should be drawn when in thin shroud over previously-seen terrain.
8
Sets whether this composite scene should be drawn when in thick shroud over unseen terrain.
Returns:
boolean
-
cm:remove_scripted_composite_scene(namestring) -
Removes a composite scene previously added by script, by the unique name given.
Parameters:
1
name
Returns:
nil
-
cm:has_scripted_composite_scene(namestring) -
Returns whether a composite scene with the specified name is currently active.
Parameters:
1
name
Returns:
boolean
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(showboolean) -
Enables or disables the shroud.
Parameters:
1
show
Returns:
nil
-
cm:take_shroud_snapshot(save snapshotboolean) -
Caches the state of the shroud across the map, so that it may later be recalled with
cm:restore_shroud_from_snapshot.Parameters:
1
Saves the snapshot in to the savegame, so that it is restored when the game is reloaded.
Returns:
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:
nil
-
cm:reset_shroud_visibility(faction keystring) -
Resets the shroud to default for the specified faction, removing any per-faction customisations that have been added with other commands in this section.
Parameters:
1
Faction key, from the
factionsdatabase table.Returns:
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:
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:
nil
-
cm:make_region_visible_in_shroud(faction keystring,region keystring) -
Removes the shroud from a specified land region for a specific faction. The region specified must be a land region.
Parameters:
1
Faction key, from the
factionstable.2
Region key, from the
campaign_map_regionstable.Returns:
nil
-
cm:make_region_seen_in_shroud(faction keystring,region keystring) -
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
Faction key, from the
factionstable.2
Region key, from the
campaign_map_regionstable.Returns:
nil
-
cm:is_region_seen_in_shroud(faction keystring,region keystring) -
Returns whether the specified land region is marked as seen in the shroud for a particular faction.
Parameters:
1
Faction key, from the
factionstable.2
Region key, from the
campaign_map_regionstable.Returns:
boolean
-
cm:make_sea_region_visible_in_shroud(region keystring) -
Removes the shroud from a specified sea region for all factions.
Parameters:
1
Region key, from the
campaign_map_regionstable.Returns:
nil
-
cm:make_sea_region_seen_in_shroud(region keystring) -
Sets the shroud state of a specified sea region for all factions to seen. The specified region must be a sea region.
Parameters:
1
Region key, from the
campaign_map_regionstable.Returns:
nil
-
cm:disable_movement_for_ai_under_shroud(player faction keystring,ai faction keystring) -
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
player faction key
2
ai faction key
Returns:
nil
-
cm:disable_shopping_for_ai_under_shroud(should disableboolean) -
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
should disable
Returns:
nil
-
cm:create_force(faction key
string,unit list
string,region key
string,x
number,y
number,id
string,exclude unique characters
boolean
) -
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.
Note that this function is automatically wrapped bycampaign_manager:create_force, which requires a slightly different set of arguments. Unless this function is called directly on the game interface thecampaign_managerwrapper function will be called, so preferentially refer to the documentation for that function instead of this.Parameters:
1
Faction key from the
factionstable.2
Unit list. This should be a comma-separated list of unit keys from the
main_unitstable.3
Region in which the force is created, from the
campaign_map_regionstable.4
Logical x co-ordinate.
5
Logical y co-ordinate.
6
ID of force. A
ScriptedForceCreatedevent 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
Prevent this force from having a unique character appointed as its general.
Returns:
nil
-
cm:create_force_with_general(faction key
string,unit list
string,region key
string,x
number,y
number,character type
string,character subtype
string,forename
string,clanname
string,surname
string,other name
string,id
string,make faction leader
boolean
) -
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.
Note that this function is automatically wrapped bycampaign_manager:create_force_with_general, which requires a slightly different set of arguments. Unless this function is called directly on the game interface thecampaign_managerwrapper function will be called, so preferentially refer to the documentation for that function instead of this.Parameters:
1
Faction key from the
factionstable.2
Unit list. This should be a comma-separated list of unit keys from the
main_unitstable.3
Region in which the force is created, from the
campaign_map_regionstable.4
Logical x co-ordinate.
5
Logical y co-ordinate.
6
Character type key, from the
agentstable.7
Character subtype key, from the
agent_subtypestable.8
Forename id. This should be a value from the
idfield of thenamestable.9
Clan name id. This should be a value from the
idfield of thenamestable. This can be used to grant a title such as "Admiral" or "Emperor". A blank string may be supplied to omit this.10
Surname id. This should be a value from the
idfield of thenamestable. A blank string may be supplied to omit this.11
Other name id. This should be a value from the
idfield of thenamestable. This is currently unused and should be set to a blank string.12
ID of force. A
ScriptedForceCreatedevent 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
Make this character the faction leader.
Returns:
nil
-
cm:create_force_with_existing_general(character lookup
string,faction key
string,unit list
string,region key
string,x
number,y
number,id
string
) -
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.
Note that this function is automatically wrapped bycampaign_manager:create_force_with_existing_general, which requires a slightly different set of arguments. Unless this function is called directly on the game interface thecampaign_managerwrapper function will be called, so preferentially refer to the documentation for that function instead of this.Parameters:
1
Character lookup string specifying the character to appoint as force commander. See
Character Lookupsfor more information.2
Faction key from the
factionstable.3
Unit list. This should be a comma-separated list of unit keys from the
main_unitstable.4
Region in which the force is created, from the
campaign_map_regionstable.5
Logical x co-ordinate.
6
Logical y co-ordinate.
7
ID of force. A
ScriptedForceCreatedevent 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:
nil
-
cm:create_force_from_family_member(family member cqi
number,faction key
string,unit list
string,region key
string,x
number,y
number,id
string
) -
Creates an army or a navy, commanded by a specific character, specified by their
family_membercqi value. This allows a character who is in the game but not present on the campaign map (e.g. they may be in the character pool, or they may have previously died) to be spawned and appointed as the commander of a new military force.
Note that this function is automatically wrapped bycampaign_manager:create_force_from_family_member, which requires a slightly different set of arguments. Unless this function is called directly on the game interface thecampaign_managerwrapper function will be called, so preferentially refer to the documentation for that function instead of this.Parameters:
1
Command-queue index value of the
family_memberscript interface associated with the character.2
Faction key from the
factionstable.3
Unit list. This should be a comma-separated list of unit keys from the
main_unitstable.4
Region in which the force is created, from the
campaign_map_regionstable.5
Logical x co-ordinate.
6
Logical y co-ordinate.
7
ID of force. A
ScriptedForceCreatedevent 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:
nil
-
cm:create_force_with_full_diplomatic_discovery(faction key
string,unit list
string,region key
string,x
number,y
number,id
string,exclude unique characters
boolean
) -
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 fromcm:create_forcein that it forces factions who can see the created force to be diplomatically aware of the force's faction.
Note that this function is automatically wrapped bycampaign_manager:create_force_with_full_diplomatic_discovery, which requires a slightly different set of arguments. Unless this function is called directly on the game interface thecampaign_managerwrapper function will be called, so preferentially refer to the documentation for that function instead of this.Parameters:
1
Faction key from the
factionstable.2
Unit list. This should be a comma-separated list of unit keys from the
main_unitstable.3
Region in which the force is created, from the
campaign_map_regionstable.4
Logical x co-ordinate.
5
Logical y co-ordinate.
6
ID of force. A
ScriptedForceCreatedevent 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
Prevent this force from having a unique character appointed as its general.
Returns:
nil
-
cm:create_force_with_budget(faction key
string,region key
string,budget
number,unit count
number,attacking
boolean,x
number,y
number,id
string
) -
Creates an army or a navy at the specified position, belonging to the specified faction, with units chosen based on the specified budget.
Note that this function is automatically wrapped bycampaign_manager:create_force_with_budget, which requires a slightly different set of arguments. Unless this function is called directly on the game interface thecampaign_managerwrapper function will be called, so preferentially refer to the documentation for that function instead of this.Parameters:
1
Faction key from the
factionstable.2
Region in which the force is created, from the
campaign_map_regionstable.3
Budget for generating an army with.
4
Number of units to generate for the army.
5
Is the force on the attacking side.
6
Logical x co-ordinate.
7
Logical y co-ordinate.
8
ID of force. A
ScriptedForceCreatedevent 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:
nil
-
cm:create_agent(faction keystring,agent typestring,agent subtypestring,xnumber,ynumber,idstring) -
Create an agent/hero character at a specified position.
Parameters:
1
Faction key from the
factionstable.2
Agent type from the
agentstable.3
Agent subtype from the
agent_subtypestable.4
Logical x co-ordinate.
5
Logical y co-ordinate.
6
ID of agent. A
ScriptedAgentCreatedevent 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.Returns:
nil
-
cm:spawn_unique_agent(faction cqinumber,agent keystring,forceboolean) -
Creates a unique agent.
Parameters:
1
Faction cqi.
2
Agent record key, from the
unique_agentstable.3
Force agent to spawn even if invalid.
Returns:
nil
-
cm:spawn_unique_agent_at_region(faction cqinumber,agent keystring,region cqinumber,forceboolean) -
Creates a unique agent in a specified region.
Parameters:
1
Faction cqi.
2
Agent record key, from the
unique_agentstable.3
The cqi of the target region.
4
Force agent to spawn even if invalid.
Returns:
nil
-
cm:spawn_unique_agent_at_character(faction cqi
number,agent key
string,character cqi
number,force
boolean
) -
Creates a unique agent at or near the position of a specified character.
Parameters:
1
Faction cqi.
2
Agent record key, from the
unique_agentstable.3
The cqi of the target character.
4
Force agent to spawn even if invalid.
Returns:
nil
-
cm:spawn_character_to_pool(faction
string,forename
string,surname
string,clanname
string,othername
string,age
number,male
boolean,agent key
string,agent subtype key
string,immortal
boolean,art set
string
) -
Spawns a new character in the specified faction's recruitment pool.
Parameters:
1
Faction key, from the
factionstable.2
Forename key. This should be a value from the
idfield of thenamestable.3
Surname key. This should be a value from the
idfield of thenamestable. A blank string may be supplied to omit this.4
Clan name key. This should be a value from the
idfield of thenamestable. This can be used to grant a title such as "Admiral" or "Emperor". A blank string may be supplied to omit this.5
Other name key. This should be a value from the
idfield of thenamestable. This is currently unused and should be set to a blank string.6
Age of character.
7
Set this character to be male or female.
8
Agent record key, from the
agentstable.9
Agent subtype key, from the
agent_subtypestable.10
Sets whether this character is immortal.
11
Art set override id, from the
campaign_character_art_setstable. A blank string may be supplied to omit this.Returns:
nil
-
cm:spawn_character_into_family_tree(faction
string,forename
string,surname
string,clanname
string,othername
string,age
number,male
boolean,father
string,mother
string,immortal
boolean,art set
string,make heir
boolean
) -
Spawns a new character into a position in the family tree of the specified faction.
Parameters:
1
Faction key, from the
factionstable.2
Forename key. This should be a value from the
idfield of thenamestable.3
Surname key. This should be a value from the
idfield of thenamestable. A blank string may be supplied to omit this.4
Clan name key. This should be a value from the
idfield of thenamestable. This can be used to grant a title such as "Admiral" or "Emperor". A blank string may be supplied to omit this.5
Other name key. This should be a value from the
idfield of thenamestable. This is currently unused and should be set to a blank string.6
Age of character.
7
Set this character to be male or female.
8
Character lookup string specifying the father of the spawned character. For more information see the documentation on
Character Lookups.9
Character lookup string specifying the mother of the spawned character. For more information see the documentation on
Character Lookups.10
Sets whether this character is immortal.
11
Art set override id, from the
campaign_character_art_setstable. A blank string may be supplied to omit this.12
Make this character the faction heir.
Returns:
nil
-
cm:respawn_character_to_pool_from_family_member(factionfaction,family memberfamily_member) -
Respawns a character that exists in the game as a family member in to their faction's recruitment pool. This allows dead characters to be resurrected.
Parameters:
1
Faction to which the character belongs.
2
family member interface associated with the character.
Returns:
boolean
-
cm:respawn_convalescing_agent(stringfaction key, numberx, numbery,character lookupstring) -
Respawns an immortal agent that has been wounded.
Parameters:
1
stringFaction key of the faction to which the agent is to belong.
2
numberx logical co-ordinate of agent.
3
numbery logical co-ordinate of agent.
4
Character lookup string - see
Character Lookupsfor more information.Returns:
nil
-
cm:spawn_rogue_army(faction keystring,xnumber,ynumber) -
Spawn a rogue army, will fail if the rogue army is alive or is flagged to naturally spawn.
Parameters:
1
Faction key, from the
factionstable.2
X coordinate on the campaign map.
3
Y coordinate on the campaign map.
Returns:
nil
-
cm:find_valid_spawn_location_for_character_from_settlement(faction key
string,region key
string,on sea
boolean,in same region
boolean,preferred spawn distance
[number]
) -
Utilises the pathfinder to locate and return a valid spawn point for a character, based around a settlement. Returns
-1, -1if invalid.Parameters:
1
Faction key, from the
factionstable.2
Region key of settlement, from the
campaign_map_regionstable.3
Specifies whether the position should be on the sea.
4
Specifies whether the spawn location should be in the same region as the specified settlement.
5
optional, default value=0
Specifies the distance at which the character should spawn.
Returns:
logicalx co-ordinatelogicaly co-ordinate
-
cm:find_valid_spawn_location_for_character_from_position(faction key
string,x
number,y
number,in same region
boolean,preferred distance
[number]
) -
Utilises the pathfinder to locate and return a valid spawn point for a character, based around a position. Returns
-1, -1if invalid.Parameters:
1
Faction key, from the
factionstable.2
Logical x co-ordinate of position around which to search.
3
Logical y co-ordinate of position around which to search.
4
Specifies whether the spawn location should be in the same region as the specified position.
5
optional, default value=0
Preferred spawn distance, in logical hexes.
Returns:
logicalx co-ordinatelogicaly co-ordinate
-
cm:find_valid_spawn_location_for_character_from_character(faction key
string,character lookup
string,in same region
boolean,preferred distance
[number]
) -
Utilises the pathfinder to locate and return a valid logical spawn point for a character, based around another character. Returns
-1, -1if invalid.Parameters:
1
Faction key, from the
factionstable.2
Character lookup string of subject character. For more information see the documentation on
Character Lookups.3
Specifies whether the spawn location should be in the same region as the specified character.
4
optional, default value=0
Preferred spawn distance, in logical hexes.
Returns:
logicalx co-ordinatelogicaly co-ordinate
-
cm:appoint_character_to_most_expensive_force(character lookupstring) -
Appoints the specified character to the command of the most expensive military force in their faction.
Parameters:
1
Character lookup string of subject character. For more information see the documentation on
Character Lookups.Returns:
nil
-
cm:appoint_character_to_force(character lookupstring,military force cqinumber) -
Appoints the specified character to the command of the specified military force.
Parameters:
1
Character lookup string of subject character. For more information see the documentation on
Character Lookups.2
Command-queue index of target military force.
Returns:
nil
-
cm:lock_starting_general_recruitment(startpos idstring,faction keystring) -
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
Startpos id of the target character. This is looked up from the
IDfield of thestart_pos_characterstable. This function cannot be used to lock recruitment of a character not present in the startpos data.2
Faction key of the character, from the
factionstable.Returns:
nil
-
cm:unlock_starting_general_recruitment(startpos idstring,faction keystring) -
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
Startpos id of the target character. This is looked up from the
IDfield of thestart_pos_characterstable. This function cannot be used to unlock recruitment of a character not present in the startpos data.2
Faction key of the character, from the
factionstable.Returns:
nil
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(character lookupstring,pointsnumber) -
Adds experience points to a specified character.
Parameters:
1
Character lookup string. For more information, see
Character Lookups.2
Experience points to award.
Returns:
nil
-
cm:add_agent_experience_through_family_member(family memberfamily_member,pointsnumber) -
Adds experience points to a character specified by its family member script interface.
Parameters:
1
Persistent family_member interface.
2
Experience points to award.
Returns:
nil
-
cm:add_experience_to_units_commanded_by_character(character lookupstring,levelnumber) -
Increases the experience of all units commanded by a specified character, by a specified level.
Parameters:
1
Character lookup string. For more information, see
Character Lookups.2
Level to increase experience of units by.
Returns:
nil
-
cm:add_experience_to_unit(unit_cqinumber,levelnumber) -
Increase the experience of the given unit, by a specified level.
Parameters:
1
The cqi of the unit
2
Level to increase experience of unit by.
Returns:
nil
-
cm:set_character_experience_disabled(disableboolean) -
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
Disable experience. Set to
falseto re-enable.Returns:
nil
-
cm:grant_unit_to_character(character lookupstring,is_garrisonboolean,unit keystring,countnumber) -
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
Character lookup string. For more information, see
Character Lookups.2
Are the units for a garrison army. Set to
falseto grant to normal army.3
Key of unit to create, from the
main_unitstable.4
[Optional] Number of untis to be added
Returns:
nil
-
cm:grant_unit_to_character_above_limit(character lookupstring,unit keystring,countnumber) -
Create and add a unit (specified by the unit key) to a character's army. The unit will be created even if their is no room for the unit in the force. Returns a table with the new units cqis'.
Parameters:
1
Character lookup string. For more information, see
Character Lookups.2
Key of unit to create, from the
main_unitstable.3
Number of untis to be added
Returns:
table
-
cm:remove_unit_by_cqi(cqinumber) -
Destroy the unit with the specified cqi.
Parameters:
1
The cqi of the unit that should be destroyed
Returns:
nil
-
cm:attack(attackerstring,defenderstring,lay siegeboolean) -
Orders the specified character to attack a target character.
This function is wrapped bycampaign_manager:attack, which performs certain pre-call checks to ensure that the command will succeed. The function may be called directly on thegame_interfaceto bypass these.Parameters:
1
Attacker character string - see
Character Lookups.2
Defender character string - see
Character Lookups.3
Instructs the attacker to lay siege to the garrison of the target character.
Returns:
boolean
-
cm:attack_queued(attackerstring,defenderstring,lay siegeboolean) -
Orders the specified character to attack a target character with a queued action.
This function is wrapped bycampaign_manager:attack_queued, which performs certain pre-call checks to ensure that the command will succeed. The function may be called directly on thegame_interfaceto bypass these.Parameters:
1
Attacker character string - see
Character Lookups.2
Defender character string - see
Character Lookups.3
Instructs the attacker to lay siege to the garrison of the target character.
Returns:
boolean
-
cm:attack_region(attackerstring,region namestring, [should_attack_immediatelyboolean]) -
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.
This function is wrapped bycampaign_manager:attack_region, which performs certain pre-call checks to ensure that the command will succeed. The function may be called directly on thegame_interfaceto bypass these.Parameters:
1
Attacker character string - see
Character Lookups.2
Target region name, from the
campaign_map_regionsdatabase table.3
optional, default value=true
Specify if the command should besiege the settlement or start the battle immediately.
Returns:
boolean
-
cm:attack_garrison_by_cqi(attackerstring,garrison cqinumber) -
Orders the specified character to initiate an attack on a garrison residence, specified by cqi.
This function is wrapped bycampaign_manager:attack_garrison_by_cqi, which performs certain pre-call checks to ensure that the command will succeed. The function may be called directly on thegame_interfaceto bypass these.Parameters:
1
Attacker character string - see
Character Lookups.2
Garrison residence cqi.
Returns:
boolean
-
cm:seek_exchange(character lookupstring,target character lookupstring,show uiboolean) -
Orders one character to seek a unit exchange with a target character, allowing troops to be swapped between the two armies they command.
This function is wrapped bycampaign_manager:seek_exchange, which performs certain pre-call checks to ensure that the command will succeed. The function may be called directly on thegame_interfaceto bypass these.Parameters:
1
Character lookup string. For more information, see
Character Lookups.2
Target character lookup string. For more information, see
Character Lookups.3
Shows the seek exchange UI.
Returns:
boolean
-
cm:move_to(character lookupstring,xnumber,ynumber) -
Orders the specified character to move to a specified logical position.
This function is wrapped bycampaign_manager:move_to, which performs certain pre-call checks to ensure that the command will succeed. The function may be called directly on thegame_interfaceto bypass these.Parameters:
1
Character lookup string. For more information, see
Character Lookups.2
Logical x co-ordinate of target position.
3
Logical y co-ordinate of target position.
Returns:
boolean
-
cm:move_to_queued(character lookupstring,xnumber,ynumber) -
Orders the specified character to move to a specified logical position with a queued action.
This function is wrapped bycampaign_manager:move_to_queued, which performs certain pre-call checks to ensure that the command will succeed. The function may be called directly on thegame_interfaceto bypass these.Parameters:
1
Character lookup string. For more information, see
Character Lookups.2
Logical x co-ordinate of target position.
3
Logical y co-ordinate of target position.
Returns:
boolean
-
cm:teleport_to(character lookupstring,xnumber,ynumber) -
Orders the specified character to immediately teleport to a specified logical position.
This function is wrapped bycampaign_manager:teleport_to, which performs certain pre-call checks to ensure that the command will succeed. The function may be called directly on thegame_interfaceto bypass these.Parameters:
1
Character lookup string. For more information, see
Character Lookups.2
Logical x co-ordinate of target position.
3
Logical y co-ordinate of target position.
Returns:
boolean
-
cm:join_garrison(character lookupstring,settlementstring) -
Orders the specified character to move into a specified garrison residence. The garrison is specified by settlement key.
This function is wrapped bycampaign_manager:join_garrison, which performs certain pre-call checks to ensure that the command will succeed. The function may be called directly on thegame_interfaceto bypass these.Parameters:
1
Character lookup string. For more information, see
Character Lookups.2
Key of settlement containing the garrison residence, from the
campaign_map_settlementstable.Returns:
boolean
-
cm:leave_garrison(character lookupstring,xnumber,ynumber) -
Orders the specified garrisoned character to leave their garrison and move to a specified logical position.
Parameters:
1
Character lookup string. For more information, see
Character Lookups.2
Logical x co-ordinate of target position.
3
Logical y co-ordinate of target position.
Returns:
nil
-
cm:cancel_actions_for(character lookupstring) -
Immediately cancels the current actions of a specified character.
Parameters:
1
Character lookup string. For more information, see
Character Lookups.Returns:
nil
-
cm:replenish_action_points(character lookupstring) -
Replenishes the action points of a specified character.
Parameters:
1
Character lookup string. For more information, see
Character Lookups.Returns:
nil
-
cm:zero_action_points(character lookupstring) -
Removes all action points from a specified character.
Parameters:
1
Character lookup string. For more information, see
Character Lookups.Returns:
nil
-
cm:set_rank_to_max(character lookupstring) -
Asssigns the maximum possible rank to the character specified. The rank assigned is returned.
Parameters:
1
Character lookup string. For more information, see
Character Lookups.Returns:
number
-
cm:kill_character(character lookupstring,destroy forceboolean) -
Kills a specified character, and optionally also the entire military force they command.
Parameters:
1
Character lookup string. For more information, see
Character Lookups.2
Destroy the character and the entire military force they command.
Returns:
nil
-
cm:kill_character_and_commanded_unit(character lookupstring,destroy forceboolean) -
Kills a specified character and their associated unit, and optionally also the entire military force they command.
Parameters:
1
Character lookup string. For more information, see
Character Lookups.2
Destroy the character and the entire military force they command.
Returns:
nil
-
cm:kill_character_and_commanded_unit_with_dt(character lookup
string,destroy force
boolean,death type
string
) -
Kills a specified character and their associated unit with a death type, and optionally also the entire military force they command.
Parameters:
1
Character lookup string. For more information, see
Character Lookups.2
Destroy the character and the entire military force they command.
3
Death type from the
death_typestable.Returns:
nil
-
cm:instantly_make_force_local_rebel(military force script interfacemilitary_force) -
Force the specified army to become local rebels in their current region or destroy the army if for some reason a rebellion couldn't be started. This can lead to faction becoming dead due to losing its last army. The original general will be killed so an army of 1 unit will be destroyed and no rebellion will be spawned.
Parameters:
1
The script interface of the target military force.
Returns:
nil
-
cm:destroy_military_force(military force cqinumber) -
Destroys a military force.
Parameters:
1
The command queue index (CQI) of the military force
Returns:
nil
-
cm:wound_character(character lookupstring,convalescence timenumber) -
Wounds a specified character, forcing them to convalesce for a specified number of turns before they can be re-appointed.
Parameters:
1
Character lookup string. For more information, see
Character Lookups.2
Number of turns this character should convalesce for until they can be re-appointed.
Returns:
nil
-
cm:retire_character(character lookupstring) -
Forces a character in to retirement, removing them from the campaign map.
Parameters:
1
Character lookup string. For more information, see
Character Lookups.Returns:
nil
-
cm:character_forced_invisible(character lookupstring,invisibilityboolean) -
Makes the character invisible or turns them back to visible.
Parameters:
1
Character lookup string. For more information, see
Character Lookups.2
invisibility
Returns:
nil
-
cm:force_agent_action_success_for_human(force successboolean) -
Force the local player's faction to succeed at all agent actions.
Parameters:
1
force success
Returns:
nil
-
cm:force_character_force_into_stance(character lookupstring,stance keystring) -
Forces the military force commanded by the specified character into the specified stance.
Parameters:
1
Character lookup string. For more information, see
Character Lookups.2
Stance key, from the
campaign_stancestable.Returns:
nil
-
cm:set_only_allow_basic_recruit_stance(force basic recruitment stancesboolean) -
Stops all military forces from entering non-default recruitment stances, such as raiding camp stance.
Parameters:
1
force basic recruitment stances
Returns:
nil
-
cm:remove_unit_from_character(character lookupstring,unit keystring) -
Remove the first instance of the specified unit from the force commanded by the specified character.
Parameters:
1
Character lookup string. For more information, see
Character Lookups.2
Key of unit to remove, from the
main_unitstable.Returns:
nil
-
cm:set_character_immortality(character lookupstring,is immortalboolean) -
Sets whether the specified character can die or not.
Parameters:
1
Character lookup string. For more information, see
Character Lookups.2
is immortal
Returns:
nil
-
cm:set_character_unique(character lookupstring,is uniqueboolean) -
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
Character lookup string. For more information, see
Character Lookups.2
is unique
Returns:
nil
-
cm:add_attack_of_opportunity_overrides(character lookupstring,force attackboolean) -
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
Character lookup string. For more information, see
Character Lookups.2
Force an attack - if set to
truethe target character will always intercept, if set tofalsethe character will always decline to intercept.Returns:
nil
-
cm:remove_attack_of_opportunity_overrides(character lookupstring) -
Removes any attack of opportunity override previously placed on the target character with
cm:add_attack_of_opportunity_overrides.Parameters:
1
Character lookup string. For more information, see
Character Lookups.Returns:
nil
-
cm:unit_belongs_to_unit_set(unit keystring,unit set keystring) -
Checks if a unit belongs to a unit set.
Parameters:
1
The key of the unit from the main_units table.
2
The key of the unit set from the unit_sets table.
Returns:
boolean
-
cm:set_army_trespass_disabled(should disableboolean) -
Globally disable or enable army trespassing penalties.
Parameters:
1
should disable
Returns:
nil
-
cm:set_character_path_traversal_speed_multiplier(charactercharacter,multipliernumber) -
Sets a locomotion speed multiplier of a character.
Parameters:
1
Character interface.
2
Multiplier value.
Returns:
nil
-
cm:clear_character_path_traversal_speed_multiplier(charactercharacter) -
Clears a locomotion speed multiplier of a character previously set with
cm:set_character_path_traversal_speed_multiplier.Parameters:
1
Character interface.
Returns:
nil
-
cm:set_forced_fastest_round_speed(force fastestboolean) -
Force or un-force the fastest round speed during the end-turn sequence. This is largely equivalent to the player clicking the skip button on the end-turn controls, except that unlike the player clicking the button the setting won't be applied to other campaigns.
Parameters:
1
force fastest
Returns:
nil
-
cm:force_normal_character_locomotion_speed_for_turn(is_enabledboolean) -
Forces any characters visible to humans to move at normal speed during the current turn if parameter is set to true.
Parameters:
1
Is normal speed enabled
Returns:
nil
-
cm:faction_apply_character_loyalty_change(faction key
string,trait key
string,loyalty change
number,threshold
number
) -
Change the loyalty of all characters in the given faction, having a given trait (if not empty string), by a given value w/o crossing a given threshold (that should have the same sign as the loyalty change).
Parameters:
1
Faction key from the
factionstable.2
Trait key from the
character_traitstable.3
Loyalty change
4
[Optional] Threshhold
Returns:
nil
-
cm:apply_character_loyalty_change(character cqinumber,loyalty changenumber,thresholdnumber) -
Change the character's loyalty by a given amount w/o crossing a given threshold (that should have the same sign as the loyalty change).
Parameters:
1
Command-queue index of the target character.
2
Loyalty change
3
[Optional] Threshhold
Returns:
nil
-
cm:get_character(character lookupstring) -
Get a
characterinterface from a lookup string. For more information, seeCharacter Lookups.Parameters:
1
Lookup string for the character
Returns:
character
-
cm:activate_stance_to_force(allowboolean,stance keystring,military force cqinumber) -
Allow or disallow a military force from using a certain stance.
Parameters:
1
Whether to allow or disallow a stance.
2
Stance key from table
campaign_stances.3
Command-queue index of the military force.
Returns:
nil
-
cm:replenish_units(character lookupstring,factornumber) -
Replenish units for the specified character.
Parameters:
1
Character lookup string
2
Amount of hp to replenish as a percentage. Valid values are from 0.0 to 1.0
Returns:
nil
-
cm:set_unit_soldiers_or_hitpoints(unitunit,hpnumber) -
Update the unit's hp to the specified value. Clamped between 0 and start_soldiers_or_hitpoints.
Parameters:
1
The unit we wish to modify
2
The new hp of the unit. The value will be clamped between 0 and start_soldiers_or_hitpoints
Returns:
nil
-
cm:damage_garrison_units(region keystring,damage amountnumber) -
Damages any units in the target garrison.
Parameters:
1
Region key from the table
regions2
Damage amount as a percantage.
Returns:
nil
-
cm:force_character_to_leave(character cqinumber) -
Forces the character to leave it's faction.
Parameters:
1
Command-queue index for the character
Returns:
nil
-
cm:set_character_scripted_time_to_leave(charactercharacter, numbertime to live) -
Sets the supplied character's scripted time to leave to the supplied number. This is displayed on the army banner as well.
Parameters:
1
Character we wish to leave.
2
numberHow many turns from now should the character leave.
Returns:
nil
-
cm:set_custom_army_info_icon(military_force_cqi
number,icon_id
string,icon_path
string,tooltip_title_key
string,tooltip_desc_key
string,param1
number,param2
number,param3
number
) -
Sets the icon path and the tooltip of a custom icon in the army name plate on the campaign map. If you want normal tooltip, specify an empty string for the tooltip_desc_key. Not saved, entirely managed by scripts.
Parameters:
1
CQI of the target military force,
2
Custom key needed for the system, user defined.
3
Supply the full path of the icon that you wish to use, Example: "ui/skins/default/sp_icon_centaur.png"
4
Localisation key for the title. This should be supplied in the full [table]_[field]_[key] localisation format, or can be a blank string.
5
Localisation key for the tooltip. This should be supplied in the full [table]_[field]_[key] localisation format, or can be a blank string.
6
[Optional] Number to be used for string formatting of the tooltip %1%.
7
[Optional] Number to be used for string formatting of the tooltip %2%.
8
[Optional] Number to be used for string formatting of the tooltip %3%.
Returns:
nil
-
cm:set_custom_army_info_icon_visibility(military_force_cqinumber,icon_idstring,visibleboolean) -
Shows or hides a custom icon in the army name plate on the campaign map, that was previously added via
cm:set_custom_army_info_icon.
Not saved, entirely managed by scripts.Parameters:
1
military_force_cqi
2
icon_id
3
visible
Returns:
nil
-
cm:force_build_siege_equipment(military forcemilitary_force) -
Shuffles available siege items and builds all possible items in the shuffled order. Returns number of siege items constructed.
Parameters:
1
military force
Returns:
number
-
cm:force_remove_siege_equipment(forcemilitary_force) -
Clears construction queue and removes all constructed siege equipment from the specified military force.
Parameters:
1
force
Returns:
nil
-
cm:send_character_to_duel(character lookupstring,convalescence timenumber) -
Send a character to duel. They will be removed from the map.
Parameters:
1
Character lookup string. For more information, see
Character Lookups.2
Convalescence time in turns.
Returns:
nil
-
cm:reserve_unit_cap(faction keystring,unit keystring) -
Reserve a unit in regard to a unit cap. This behaves as if the unit is existing in an army somewhere, meaning the faction won't be able to recruit a capped unit that it otherwise could.
Parameters:
1
Faction key, from the
factionsdatabase table.2
Unit key, from the
main_unitsdatabase table.Returns:
nil
-
cm:release_unit_cap(faction keystring,unit keystring) -
Release a unit cap reservation previously made with
cm:reserve_unit_cap. Exercise caution using this function, as it releases the unit cap without checking that a reservation was previously placed.Parameters:
1
Faction key, from the
factionsdatabase table.2
Unit key, from the
main_unitsdatabase table.Returns:
nil
-
cm:change_unit_health(unit cqinumber,health changenumber) -
Change the health of the given unit by a given fraction. This can be a positive number to heal the unit or a negative number to damage the unit.
Parameters:
1
Command-queue index value for the specified unit.
2
Health change value.
Returns:
nil
-
cm:add_unit_stat_bonuses(unit cqinumber,stat bonusstring,bonus valuenumber) -
Add stat bonuses to a specified unit.
Parameters:
1
Command-queue index value for the specified unit.
2
Unit statistics bonus key, from the
campaign_unit_stat_bonusesdatabase table.3
Bonus value.
Returns:
nil
-
cm:add_unit_no_muster_recruitment(character lookupstring,unit keystring,turnsnumber) -
Create and add a unit mid-recruitment to a character's army. The unit will only be created if there is room for the unit in the force. The recruitment is free, and it will be converted to a unit in the provided set of turns. The recruitment reserves a unit slot in the army.
Parameters:
1
Character lookup string. For more information, see
Character Lookups.2
Unit key, from the
main_unitsdatabase table.3
Turns over which the recruitment should take place.
Returns:
nil
-
cm:reassign_character_to_faction(character lookupstring,faction keystring) -
Reassign a character to another faction. Not used in the retail game and thus not properly tested. Use with cauton!
Parameters:
1
Character lookup string. For more information, see
Character Lookups.2
Faction key, from the
factionsdatabase table.Returns:
nil
-
cm:make_adopted_child(child lookupstring,parent lookupstring) -
Make a parent adopt a child
Parameters:
1
Character lookup string. For more information, see
Character Lookups.2
Character lookup string. For more information, see
Character Lookups.Returns:
nil
-
cm:appoint_character_as_faction_heir(character lookupstring, [apply costboolean]) -
Appoint a character as heir to their faction (scion), optionally skipping applying the respective cost.
Parameters:
1
Character lookup string. For more information, see
Character Lookups.2
optional, default value=true
Whether resource cost should be applied. Resource cost is defined in resource_costs table with record phar_map_appoint_faction_heir_cost
Returns:
nil
-
cm:marry_characters(character lookupstring,character lookupstring) -
Marry the two specified characters, optionally providing marriage type among arranged/diplomatic/political, with the first being the default. The two characters must be in the same faction for arranged marriage and in different factions for the other two marriages. For diplomatic marriage, the first character is given away to the other faction.
Parameters:
1
Character lookup string. For more information, see
Character Lookups.2
Character lookup string. For more information, see
Character Lookups.Returns:
nil
-
cm:arrange_marriage_to_new_random_character(character lookupstring, [apply costboolean]) -
Create a spouse for the specified character and marry the 2 characters
Parameters:
1
Character lookup string. For more information, see
Character Lookups.2
optional, default value=true
Whether resource cost should be applied. Resource cost is defined in resource_costs table with record phar_map_arranged_marriage_to_a_commoner_cost
Returns:
nil
-
cm:divorce_character(character lookupstring) -
Divorce the specified character from their spouse. The given character's faction is the instigator of the divorce.
Parameters:
1
Character lookup string. For more information, see
Character Lookups.Returns:
nil
-
cm:add_units_to_faction_mercenary_pool(faction cqinumber,unit keystring,countnumber) -
Adds one or more of a specified unit to the specified faction's mercenary pool.
Parameters:
1
CQI of the subject faction.
2
Unit key, from the
main_unitstable.3
Number of units to add.
Returns:
nil
-
cm:num_units_in_faction_mercenary_pool(faction cqinumber,unit keystring) -
Return count of a specified unit in the factions mercenary pool.
Parameters:
1
CQI of the subject faction.
2
Unit key, from the
main_unitsdatabase table.Returns:
number
-
cm:add_units_to_province_mercenary_pool_by_region(region keystring,unit keystring,countnumber) -
Adds one or more of a specified unit to the specified province mercenary pool. The province is specified by a region within it.
Parameters:
1
Region key of a region within the target province, from the
campaign_map_regionstable.2
Unit key, from the
main_unitsdatabase table.3
Number of units to add.
Returns:
nil
-
cm:add_unit_to_faction_mercenary_pool(faction
faction,unit key
string,count
number,replenishment chance
number,max units
number,max per turn
number,xp level
number,faction restricted record
[string],subculture restricted record
[string],tech restricted record
[string]
) -
Add a unit to the mercenary pool of the specified faction. The new unit(s) will replace any existing entry with the same unit record.
Parameters:
1
Subject faction.
2
Unit key, from the
main_unitsdatabase table.3
Number of units to add to the mercenary pool.
4
replenishment chance percentage.
5
The max number of units that can be in the pool.
6
The max number of units that can be replenished in the pool per turn.
7
The experience level of the units when recruited.
8
optional, default value=nil
Faction restricted record.
9
optional, default value=nil
Subculture restricted record.
10
optional, default value=nil
Technology restricted record.
Returns:
nil
-
cm:add_unit_to_faction_mercenary_pool_with_cooldown(faction
faction,unit key
string,count
number,cooldown
number,max units
number,units recharged
number,xp level
number,faction restricted record
[string],subculture restricted record
[string],tech restricted record
[string]
) -
Add a unit to the mercenary pool of the specified faction, with a cooldown based recharge. The new unit(s) will replace any existing entry with the same unit record.
Parameters:
1
Subject faction.
2
Unit key, from the
main_unitsdatabase table.3
Number of units to add to the mercenary pool.
4
How frequently (in turns) the unit replenishes.
5
The max number of units that can be in the pool.
6
The number of units recharged each time the cooldown finishes.
7
The experience level of the units when recruited.
8
optional, default value=nil
Faction restricted record.
9
optional, default value=nil
Subculture restricted record.
10
optional, default value=nil
Technology restricted record.
Returns:
nil
-
cm:add_custom_unit_to_faction_mercenary_pool(faction key
string,custom unit
custom_unit,count
number,replenishment chance
number,max units
number,max per turn
number,xp level
number,faction restricted record
[string],subculture restricted record
[string],tech restricted record
[string]
) -
Add a
custom_unitto the mercenary pool of the specified faction. The new unit(s) will replace any existing entry with the same unit record.Parameters:
1
Faction key, from the
factionstable.2
Custom unit to add.
3
Number of units to add to the mercenary pool.
4
replenishment chance percentage.
5
The max number of units that can be in the pool.
6
The max number of units that can be replenished in the pool per turn.
7
The experience level of the units when recruited.
8
optional, default value=nil
Faction restricted record.
9
optional, default value=nil
Subculture restricted record.
10
optional, default value=nil
Technology restricted record.
Returns:
nil
-
cm:remove_unit_from_faction_mercenary_pool(factionfaction,unit keystring,custom idstring) -
Removes a unit from the specified faction mercenary pool. A custom id key may be supplied to further specify the unit to remove.
Parameters:
1
Subject faction.
2
Unit key, from the
main_unitsdatabase table.3
Custom id of unit to remove. A blank string may be supplied to specify no custom id.
Returns:
nil
-
cm:get_max_units_in_faction_mercenary_pool(faction cqinumber,unit keystring,custom idstring) -
Returns the maximum supported number there can be of a specified unit in the specified faction's mercenary pool.
Parameters:
1
Faction command-queue index value.
2
Unit key, from the
main_unitsdatabase table.3
Custom id of unit to look for. A blank string may be supplied to specify no custom id.
Returns:
nil
-
cm:add_unit_to_province_mercenary_pool(region
region,unit key
string,count
number,chance
number,max units
number,max per turn
number,xp level
number,faction restricted record
[string],subculture restricted record
[string],tech restricted record
[string]
) -
Adds one or more of a specified unit to the specified province mercenary pool. The province is specified by a region within it.
Parameters:
1
Region within the subject province.
2
Unit key, from the
main_unitsdatabase table.3
Number of units to add to the mercenary pool.
4
Replenishment chance percentage.
5
The max number of units that can be in the pool.
6
The max number of units that can be replenished in the pool per turn.
7
The experience level of the units when recruited.
8
optional, default value=nil
Faction restricted record.
9
optional, default value=nil
Subculture restricted record.
10
optional, default value=nil
Technology restricted record.
Returns:
nil
-
cm:remove_unit_from_province_mercenary_pool(regionregion,unit keystring,custom idstring) -
Removes a unit from the specified province mercenary pool. A custom id key may be supplied to further specify the unit to remove.
Parameters:
1
Region within the target province.
2
Key of unit to remove.
3
Custom id of unit to remove. A blank string may be supplied to specify no custom id.
Returns:
nil
-
cm:add_circle_area_trigger(x
number,y
number,radius
number,trigger name
string,character lookup
string,trigger on enter
boolean,trigger on exit
boolean,trigger once
boolean
) -
Establishes a circular area trigger monitor around a specified display position, with a specified character lookup string filter. This monitor will trigger an
AreaEnteredorAreaExitedscript event if a character that matches the specified filter moves through the specified circular area boundary.Parameters:
1
x display co-ordinate.
2
y display co-ordinate.
3
Radius of circle.
4
Trigger name. Multiple trigger areas with the same name behave as a single trigger.
5
Character lookup string, specifying characters for which this trigger area will fire events. For more information, see
Character Lookups.6
Specifies whether an
AreaEnteredevent is fired when a matching character enters the trigger area.7
Specifies whether an
AreaExitedevent is fired when a matching character exits the trigger area.8
Specifies whether the trigger continues monitoring after it fires its first event.
Returns:
nil
-
cm:add_outline_area_trigger(trigger name
string,character lookup
string,trigger on enter
boolean,trigger on exit
boolean,trigger once
boolean,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
AreaEnteredorAreaExitedscript event if a character that matches the specified filter moves through the specified circular area boundary.Parameters:
1
Trigger name. Multiple trigger areas with the same name behave as a single trigger.
2
Character lookup string, specifying characters for which this trigger area will fire events. For more information, see
Character Lookups.3
Specifies whether an
AreaEnteredevent is fired when a matching character enters the trigger area.4
Specifies whether an
AreaExitedevent is fired when a matching character exits the trigger area.5
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:
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(trigger namestring) -
Removes any area triggers established with the supplied name.
Parameters:
1
trigger name
Returns:
nil
-
cm:force_add_trait(character lookupstring,trait keystring, [trait pointsnumber]) -
Grant the specified trait to the specified character. If the character already has the trait, a trait point will be added.
Parameters:
1
Character lookup string. For more information, see
Character Lookups.2
Trait key, from the
character_traitstable.3
optional, default value=1
Number of trait points to add.
Returns:
nil
-
cm:force_remove_trait(character lookupstring,trait keystring) -
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
Character lookup string. For more information, see
Character Lookups.2
Trait key, from the
character_traitstable.Returns:
nil
-
cm:force_remove_all_traits(character lookupstring) -
Remove all traits from the specified character. If the character is past the point of no return in a trait, it will be removed anyway.
Parameters:
1
Character lookup string. For more information, see
Character Lookups.Returns:
nil
-
cm:get_antitrait_for_trait(trait keystring) -
Returns the antitrait of a specified trait, based on the data in the
trait_to_antitraitdatabase table.Parameters:
1
Trait key, from the
character_traitstable.Returns:
string
-
cm:set_ignore_immortality_by_trait(character lookupstring,ignore immortality by traitboolean) -
Sets the
ignore_immortality_by_traitflag of a character. This is useful, in conjunction withcm:set_character_immortality, to kill a character for certain, ignoring their immortality state.Parameters:
1
Character lookup string. For more information, see
Character Lookups.2
ignore immortality by trait
Returns:
nil
-
cm:get_traits_from_trait_info_with_prefix(prefixstring) -
Returns a numerically-indexed table containing all traits keys from the
character_traitsdatabase table starting with the supplied prefix.Parameters:
1
prefix
Returns:
table
-
cm:reset_not_received_traits_progress(character lookupstring) -
Resets the point progress of all traits that are not yet leveled up for a specified character.
Parameters:
1
Character lookup string. For more information, see
Character Lookups.Returns:
nil
-
cm:force_add_ancillary(character lookupstring,ancillary keystring, [suppress event messageboolean]) -
Grant the specified ancillary to the specified character.
Parameters:
1
Character lookup string. For more information, see
Character Lookups.2
Ancillary key, from the
ancillariestable.3
optional, default value=false
Whether to suppress the event message that the ancillary was added.
Returns:
nil
-
cm:force_add_and_equip_ancillary(character lookup
string,ancillary key
string,suppress event message
[boolean]
) -
Grant the specified ancillary to the specified character and equips it. If another ancillary is equipped in the relevant slot then that ancillary is unequipped.
Parameters:
1
Character lookup string. For more information, see
Character Lookups.2
Ancillary key, from the
ancillariestable.3
optional, default value=false
Whether to suppress the event message that the ancillary was added.
Returns:
nil
-
cm:force_remove_ancillary(character lookupstring,ancillary keystring,remove to poolboolean) -
Remove the specified ancilliary from the specified character.
Parameters:
1
Character lookup string. For more information, see
Character Lookups.2
Ancillary key, from the
ancillariestable.3
Removes the ancillary from the character but leaves it in the pool of available ancillaries.
Returns:
nil
-
cm:force_remove_all_ancillaries_of_type(character lookupstring,ancillary typestring) -
Remove all ancillaries of the specified type from the specified force.
Parameters:
1
Character lookup string. For more information, see
Character Lookups.2
Ancillary type key, from the
ancillary_typestable.Returns:
nil
-
cm:add_ancillary_to_faction(faction keystring,ancillary keystring,display eventboolean) -
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 key, from the
factionstable.2
Ancillary key, from the
ancillariestable.3
Sets whether the associated event feed event should be displayed.
Returns:
nil
-
cm:force_remove_ancillary_from_faction(faction key
string,ancillary key
string,remove from characters
[boolean]
) -
Remove all instances of the specified ancillary from every character, and the shared ancillary pool, of the specified faction.
Parameters:
1
Faction key, from the
factionstable.2
Ancillary key, from the
ancillariestable.3
optional, default value=true
Remove from all characters
Returns:
nil
-
cm:get_ancillary_category(ancillary keystring) -
Returns the category of a supplied ancillary. The returned category will be a key from the
ancillaries_categoriesdatabase table.Parameters:
1
Ancillary key, from the
ancillariestable.Returns:
string
-
cm:force_add_skill(character lookupstring,skill keystring) -
Grant the specified skill to the specified character, or adds a point if they already have it.
Parameters:
1
Character lookup string. For more information, see
Character Lookups.2
Skill key, from the
character_skillstable.Returns:
nil
-
cm:force_remove_skill(character lookupstring,skill keystring,refund skill pointboolean) -
Forcibly removes a skill from a character.
Parameters:
1
Character lookup string. For more information, see
Character Lookups.2
Skill key, from the
character_skillstable.3
Whether to refund a skill point when the skill is successfully removed.
Returns:
nil
-
cm:force_reset_skills(character lookupstring) -
Completely resets the skill points of the target character. Does not remove background skills.
Parameters:
1
Character lookup string. For more information, see
Character Lookups.Returns:
nil
-
cm:set_non_scripted_traits_disabled(disableboolean) -
Prevents or allows the application of traits by
common.trait, which is intended to be the general-purpose trait-adding function.cm:force_add_traitwill still work even with this restriction in place.Parameters:
1
disable
Returns:
nil
-
cm:set_non_scripted_ancillaries_disabled(disableboolean) -
Prevents or allows the application of ancillaries by
common.ancillary, which is intended to be the general-purpose ancillary-adding function.cm:force_add_ancillarywill still work even with this restriction in place.Parameters:
1
disable
Returns:
nil
-
cm:add_trait_to_character_by_family_member(family member cqi
number,trait key
string,show message
boolean,points
[trait]
) -
Grants the specified trait to a character specified by a family member. If character object doesn't exist, the trait is added to the persistent data of the character.
Parameters:
1
family member cqi
2
trait key
3
show message
4
traitoptional, default value=1
points
Returns:
nil
-
cm:change_localised_faction_name(faction keystring,name keystring) -
Changes the name of a faction. The new name is specified by full localised text key, in the [table]_[key]_[field] format.
Parameters:
1
Faction key, from the
factionstable.2
Localised name key, in the [table]_[key]_[field] format.
Returns:
nil
-
cm:change_custom_faction_name(faction keystring,namestring) -
Changes the name of a faction. The new name is specified directly as a string.
Parameters:
1
Faction key, from the
factionstable.2
New name for the faction.
Returns:
nil
-
cm:change_custom_settlement_name(settlementsettlement,name keystring) -
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 object - see the campaign model hierarchy documentation for more information about this interface.
2
Localised name key, in the [table]_[key]_[field] format.
Returns:
nil
-
cm:change_localised_settlement_name(settlementsettlement,namestring) -
Changes the name of a faction. The new name is specified directly as a string.
Parameters:
1
Settlement object - see the campaign model hierarchy documentation for more information about this interface.
2
New name for the faction.
Returns:
nil
-
cm:change_custom_region_name(regionregion,name keystring) -
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_nameinstead.Parameters:
1
Region object - see the campaign model hierarchy documentation for more information about this interface.
2
Localised name key, in the [table]_[key]_[field] format.
Returns:
nil
-
cm:change_localised_region_name(regionregion,namestring) -
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_nameinstead.Parameters:
1
Region object - see the campaign model hierarchy documentation for more information about this interface.
2
New name for the region.
Returns:
nil
-
cm:change_custom_unit_name(unitunit,name keystring) -
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 object - see the campaign model hierarchy documentation for more information about this interface.
2
Localised name key, in the [table]_[key]_[field] format.
Returns:
nil
-
cm:change_localised_unit_name(unitunit,namestring) -
Changes the name of a unit. The new name is specified directly as a string.
Parameters:
1
Unit object - see the campaign model hierarchy documentation for more information about this interface.
2
New name for the unit.
Returns:
nil
-
cm:set_custom_army_name_key(military force cqinumber,name keystring) -
Sets a custom name key for the specified military force. The new name is specified by full localised text key, in the [table]_[key]_[field] format.
Parameters:
1
military force cqi
2
Localised name key, in the [table]_[key]_[field] format.
Returns:
nil
-
cm:remove_custom_army_name_key(military force cqinumber) -
Removes any custom name associated with the supplied military force. The military force is specified by command queue index value.
Parameters:
1
military force cqi
Returns:
nil
-
cm:set_tax_rate(faction keystring,tax ratenumber) -
Sets the tax rate for a specified faction. The tax rate may be one of the following integer values:
Value Description
0minimal 1low 2normal 3high 4extortionate Parameters:
1
Faction key, from the
factionstable.2
Tax rate, from the table above.
Returns:
nil
-
cm:exempt_region_from_tax(region keystring,exemptboolean) -
Exempts, or un-exempts, the province containing specified region from tax contributions.
Parameters:
1
Region key, from the
campaign_map_regionstable.2
Exempt province from tax.
Returns:
nil
-
cm:exempt_province_from_tax_for_all_factions_and_set_default(region keystring,exemptboolean) -
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
Region key, from the
campaign_map_regionstable.2
Exempt province from tax.
Returns:
nil
-
cm:disable_rebellions_worldwide(disableboolean) -
Disables or re-enables all rebellions across the map.
Parameters:
1
disable
Returns:
nil
-
cm:force_rebellion_in_region(region keystring,unitsnumber,xnumber,ynumber,suppress messageboolean) -
Force a rebellion of a specified size in the specified region.
Parameters:
1
Region key, from the
campaign_map_regionstable.2
Maximum number of units in the spawned rebellion.
3
Logical x co-ordinate of target position.
4
Logical y co-ordinate of target position.
5
Suppress the event message related to the rebellion.
Returns:
nil
-
cm:treasury_mod(faction keystring,amountnumber) -
Immediately modifies the treasury of the specified faction by the specified amount.
Parameters:
1
Faction key, from the
factionstable.2
Treasury modification. This value must be positive.
Returns:
nil
-
cm:get_unit_keys_from_faction_pool(faction keystring) -
Returns a numerically-indexed table with all unit keys given faction can currently recruit from the faction recruitment pool.
Parameters:
1
Faction key, from the
factionstable.Returns:
table
-
cm:set_public_order_of_province_for_region(region keystring,public ordernumber) -
Sets the public order value for the province containing the specified region.
Parameters:
1
Region key, from the
campaign_map_regionstable.2
Public order value.
Returns:
nil
-
cm:set_public_order_disabled_for_province(faction keystring,province keystring,disableboolean) -
Disables or re-enables public order in the specified province for a specified faction.
Parameters:
1
Faction key, from the
factionsdatabase table.2
Province key, from the
provincesdatabase table.3
Should disable public order.
Returns:
nil
-
cm:set_public_order_disabled_for_province_for_region(region keystring,disableboolean) -
Disables or re-enables public order in the province containing the specified region.
Parameters:
1
Region key, from the
campaign_map_regionstable.2
Disable public order.
Returns:
nil
-
cm:set_public_order_disabled_for_province_for_region_for_all_factions_and_set_default(region key
string,disable
boolean
) -
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
Region key, from the
campaign_map_regionstable.2
Disable public order.
Returns:
nil
-
cm:add_development_points_to_region(region keystring,development pointsnumber) -
Adds development points to the province containing the specified region.
Parameters:
1
Region key, from the
campaign_map_regionstable.2
Developments points to add.
Returns:
nil
-
cm:set_imperium_level_change_disabled(disableboolean) -
Disables or re-enables imperium level changes across the whole campaign.
Parameters:
1
disable
Returns:
nil
-
cm:set_region_abandoned(region keystring) -
Immediately sets the specified to be abandoned. Nothing will happen if an already-abandoned region is specified.
Parameters:
1
Region key, from the
campaign_map_regionstable.Returns:
nil
-
cm:set_region_can_be_traded_if_not_adjacent(region keystring,can_be_traded_if_not_adjacentboolean) -
Set if a region can be traded to other faction even when not adjacent to that faction
Parameters:
1
Region key, from the
campaign_map_regionstable.2
can_be_traded_if_not_adjacent
Returns:
nil
-
cm:transfer_region_to_faction(region keystring,faction keystring) -
Immediately transfers ownership of the specified region to the specified faction.
Parameters:
1
Region key, from the
campaign_map_regionstable.2
Faction key, from the
factionstable.Returns:
nil
-
cm:change_region_owner(region keystring,faction keystring) -
Immediately transfers ownership of the specified region to the specified faction.
Parameters:
1
Region key, from the
campaign_map_regionstable.2
Faction key, from the
factionstable.Returns:
nil
-
cm:change_region_slot_owner(region keystring,faction keystring) -
Immediately transfers ownership of the specified region slot to the specified faction if said faction can own an foreign ERS or is the owner of the region.
Parameters:
1
Region slot key, extract via the slot script interface function "slot_key()".
2
Faction key, from the
factionstable.Returns:
nil
-
cm:create_storm_for_region(region keystring,storm strengthnumber,durationnumber, [storm typestring]) -
Creates a storm of a given type in a given region. This calls the function of the same name on the game interface, but adds validation and output.
Parameters:
1
Region key, from the
campaign_map_regionstable.2
Storm strength. The strength of existing storm instances can be looked up in the
campaign_stormstable.3
Duration of the storm in turns.
4
optional, default value=false
Storm type, looked up from the
campaign_storm_typestable. By default, this is set to"land_storm"for a land region and"wandering_decaying_sea_storm"for a sea region.Returns:
nil
-
cm:clear_province_initiative(province keystring,faction keystring) -
Cancels any currently-active province initiative for a specified province and faction.
Parameters:
1
Province key, from the
provincesdatabase table.2
Faction key, from the
factionsdatabase table.Returns:
nil
-
cm:set_technology_research_disabled(disableboolean) -
Disable or re-enable technology functionality in game for the player.
Parameters:
1
disable
Returns:
nil
-
cm:set_liberation_options_disabled(disableboolean) -
Disables or re-enables post-battle liberation options for the player.
Parameters:
1
disable
Returns:
nil
-
cm:set_ui_notification_of_victory_disabled(disableboolean) -
Disable or re-enable notification of victory for the UI.
Parameters:
1
disable
Returns:
nil
-
cm:remove_god_from_conflict(god keystring) -
Remove god from conflict by given god record key.
Parameters:
1
God key from the
campaign_godstable.Returns:
nil
-
cm:politics_get_ministerial_posts(faction keystring,tiernumber,takenboolean) -
Gets the amount of ministerial posts that are available or unavailable in a given tier.
Parameters:
1
Faction key, from the
factionstable.2
The tier in which to check for posts. -1 for all tiers
3
Whether to check for available or unavailable posts
Returns:
number
-
cm:politics_enabled(faction keystring) -
Checks if politics feature is enabled for faction
Parameters:
1
Faction key, from the
factionstable.Returns:
boolean
-
cm:faction_set_potential_modifier(factionfaction,modifier valuenumber) -
Sets an additive modifier for the faction potential of the specified faction.
Parameters:
1
faction
2
modifier value
Returns:
nil
-
cm:faction_set_total_potential_override_value(faction
faction,use override
boolean,override value
number
) -
Sets an absolute override value for the faction potential of the specified faction.
Parameters:
1
faction
2
use override
3
override value
Returns:
nil
-
cm:faction_set_free_instant_constructions(faction keystring,constructionsnumber) -
Sets the number of free instant constructions the specified faction has.
Parameters:
1
Faction key, from the
factionsdatabase table.2
Number of instant constructions.
Returns:
nil
-
cm:get_random_desired_resource_from_faction(faction keystring, [most desiredboolean]) -
Returns a random resource from those that a faction most or least desires. If the optional flag is either
trueor not set, then a random resource from those the faction most desires is returned. If the optional flag isfalsethen a random resource from those the faction least desires is returned. If the faction has no relevant resources it most or least desires, a random resource is returned.Parameters:
1
Faction key, from the
factionsdatabase table.2
optional, default value=true
Pick random resource from most-desired resource list, instead of from the least-desired resource list.
Returns:
nil
-
cm:set_battle_details_override_for_region(region key
string,battle type
string,redirection
string,redirection_catchment
string,time of day
string
) -
Override the battle details for battles of the given type in the specified region (empty string for any if you want to default it). Pass 'suffix' for redirection_catchment if you want to use redirection as a suffix to the default map.
Parameters:
1
Region to override.
2
Override battle type.
3
Battle folder override.
4
Redirection catchement by key, make sure it's valid for the supplied battle type and battel folder combination.
5
Time of day override, valid options are empty string, "day" or "night".
Returns:
nil
-
cm:set_can_autoresolve_settlement_battle(settlement key
string,can_autoresolve
boolean,tooltip loc path
[string]
) -
Sets a flag weather attacker can autoresolve settlement battles for the supplied settlement by key.
Parameters:
1
Settlement to set the flag for.
2
New value for the flag.
3
optional, default value=nil]
stringtooltip loc path, Localisation key for the autoresolve button. This should be supplied in the full [table]_[field]_[keyLocalisation key for the autoresolve button. This should be supplied in the full [table]_[field]_[key] localisation format, or can be a blank string.
Returns:
nil
-
cm:set_custom_settlement_info_icon(region_key
string,icon_id
string,icon_path
string,tooltip_title_key
string,tooltip_desc_key
string,param1
number,param2
number,param3
number
) -
Sets the icon path and the tooltip key of a custom icon in the settlement name plate on the campaign map. Not saved, entirely managed by scripts.
Parameters:
1
Region key of the target region.
2
Custom key needed for the system, user defined.
3
Supply the full path of the icon that you wish to use, Example: "ui/skins/default/sp_icon_centaur.png"
4
Localisation key for the title. This should be supplied in the full [table]_[field]_[key] localisation format, or can be a blank string.
5
Localisation key for the tooltip. This should be supplied in the full [table]_[field]_[key] localisation format, or can be a blank string.
6
[Optional] Number to be used for string formatting of the tooltip %1%.
7
[Optional] Number to be used for string formatting of the tooltip %2%.
8
[Optional] Number to be used for string formatting of the tooltip %3%.
Returns:
nil
-
cm:set_custom_settlement_info_icon_visibility(region_keystring,icon_idstring,visibleboolean) -
Shows or hides a custom icon in the settlement name plate on the campaign map, that was previously added via
cm:set_custom_settlement_info_icon.
Not saved, entirely managed by scripts.Parameters:
1
region_key
2
icon_id
3
visible
Returns:
nil
-
cm:set_fight_battle_at_night(faction_keystring,is_night_battleboolean) -
Sets/unsets the battle to be fought at night.
Parameters:
1
faction_key
2
is_night_battle
Returns:
nil
-
cm:set_force_has_retreated_this_turn(charactercharacter) -
Sets the has reatreated flag for the specified character
Parameters:
1
character
Returns:
nil
-
cm:set_skip_all_but_faction(factionfaction,skipboolean) -
Enables or disables automatically skipping the turn for all except the faction specified. No turn-start notifications are sent for skipped turns. Avoid using in multiplayer!
Parameters:
1
faction
2
skip
Returns:
nil
-
cm:set_skip_for_faction(factionfaction,is_skippedboolean) -
Enables or disables automatically skipping the turn for the provided faction. No turn-start notifications are sent for skipped turns. Avoid using in multiplayer!
Parameters:
1
faction
2
is_skipped
Returns:
nil
-
cm:set_auto_end_turn_all_but_faction(factionfaction,skipboolean) -
Enables or disables automatically ending the turn for all factions, except the faction specified. Turn-start notifications are sent for factions that auto-end their turn. Avoid using in multiplayer!
Parameters:
1
faction
2
skip
Returns:
nil
-
cm:set_auto_end_turn_for_faction(factionfaction,is_skippedboolean) -
Enables or disables automatically ending the turn for the provided faction. Turn-start notifications are sent for factions that auto-end their turn. Avoid using in multiplayer!
Parameters:
1
faction
2
is_skipped
Returns:
nil
-
cm:set_unit_script_name_by_cqi(unit_cqinumber,script_namestring) -
Set the script name (for usage in battle) for a unit by cqi.
Parameters:
1
unit_cqi
2
script_name
Returns:
nil
-
cm:upgrade_unit(unit_cqinumber,unit_keystring) -
Force a unit by CQI to upgrade to a unit by record.
Parameters:
1
Unit to upgrade.
2
Target unit record key.
Returns:
nil
-
cm:set_region_supply_points(region_keystring,new_supply_pointsnumber) -
Set region's supply points
Parameters:
1
Target region record key.
2
New supply points value.
Returns:
nil
-
cm:heal_region_garrison(region cqinumber,factornumber) -
Heals the garrison army (and navy, where applicable) in the specified region by the specified factor or back to full health. The region is specified by cqi.
Parameters:
1
Command-queue index of the target region.
2
[optional] Amount of hp to replenish as a percentage. Valid values are from 0.0 to 1.0. Default is 1(full health).
Returns:
nil
-
cm:change_dynasty_ruler(dynasty_line_key
string,new_ruling_faction_key
string,won_legitimacy_war
[boolean]
) -
Changes the ruler of the current dynasty from the specified Dynasty Line (Legitimacy Path) to the faction leader of the specified faction
Parameters:
1
dynasty_line_key
2
new_ruling_faction_key
3
optional, default value=false
won_legitimacy_war
Returns:
nil
-
cm:trigger_mission(faction keystring,mission keystring,fire immediatelyboolean) -
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.Parameters:
1
Faction key, from the
factionstable.2
Mission key, from the
missionstable.3
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.
Returns:
boolean
-
cm:trigger_custom_mission(faction keystring,mission keystring) -
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
Faction key, from the
factionstable.2
Mission key, from missions.txt file.
Returns:
nil
-
cm:trigger_custom_mission_from_string(faction keystring,missionstring) -
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
Faction key, from the
factionstable.2
Mission definition string.
Returns:
nil
-
cm:cancel_mission(faction keystring,mission keystring) -
Cancels an active mission, using the mission key.
Parameters:
1
Faction key, from the
factionstable.2
Mission key, from the
missionstable.Returns:
nil
-
cm:cancel_mission_by_id(faction keystring,custom idstring) -
Cancels an active mission, using a custom id for the mission. A custom id can be set as a property in the text definition for a mission defined by string, prior to creation.
Parameters:
1
Faction key, from the
factionstable.2
Custom id for the mission.
Returns:
nil
-
cm:trigger_mission_with_targets(faction cqi
number,mission key
string,target faction cqi
string,secondary faction cqi
string,character cqi
string,military force cqi
string,region cqi
string,settlement cqi
string
) -
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_junctionstable in order to trigger.
A value of0may be supplied to omit a particular type of target.Parameters:
1
Command-queue index of the faction to which the mission is issued. This must be supplied.
2
Mission key, from the
missionstable.3
Command-queue index of a target faction.
0may be specified to omit this target (and other target arguments following this one).4
Command-queue index of a second target faction. May be
0.5
Command-queue index of a target character. May be
0.6
Command-queue index of a target military force. May be
0.7
Command-queue index of a target region. May be
0.8
Command-queue index of a target settlement. May be
0.Returns:
nil
-
cm:toggle_mission_generation(can generateboolean) -
Sets whether the campaign director system can generate missions or not.
Parameters:
1
can generate
Returns:
nil
-
cm:add_custom_pending_mission_from_string(recipient faction
faction,issuing faction
faction,mission
string
) -
Triggers a custom pending mission from a string passed into the function. A pending mission is a mission created but not formally issued to the recipient faction.
The mission string must be supplied in a custom format - see the missions.txt that commonly accompanies a campaign for examples.Parameters:
1
Recipient faction object.
2
Issuing faction object.
3
Mission definition string.
Returns:
nil
-
cm:clear_pending_missions(factionfaction) -
Clears any unissued pending missions for the supplied faction.
Parameters:
1
Faction.
Returns:
nil
-
cm:set_mission_display_faction(mission faction
string,display faction
string,mission key
string,custom id
[string]
) -
Sets the faction displayed on the mission.
Parameters:
1
Faction key of the faction to which the mission is assigned, from the
factionsdatabase table.2
Faction key of the faction to display on the mission, from the
factionsdatabase table.3
Key of the mission, from the
missionsdatabase table.4
optional, default value=nil
Custom id of the target mission. A custom id can be set as a property in the text definition for a mission defined by string, prior to creation.
Returns:
nil
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(mission keystring,script keystring,text keystring) -
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
Mission key, from the
missionstable.2
Key of the particular scripted objective associated with the mission.
3
Localised text key, in the full [table]_[field]_[key] format.
Returns:
nil
-
cm:set_scripted_mission_position(mission keystring,script keystring,xnumber,ynumber) -
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
Mission key, from the
missionstable.2
Key of the particular scripted objective associated with the mission.
3
Logical x co-ordinate of the updated position.
4
Logical y co-ordinate of the updated position.
Returns:
nil
-
cm:complete_scripted_mission_objective(mission key
string,script key
string,is success
boolean,custom_id
string
) -
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
Mission key, from the
missionstable.2
Key of the particular scripted objective associated with the mission.
3
Objective was completed successfully.
4
Custom ID of the mission.
Returns:
nil
-
cm:trigger_incident(faction keystring,incident keystring,fire immediatelyboolean) -
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
Faction key, from the
factionstable.2
Incident key, from the
incidentstable.3
Set the incident to fire immediately.
Returns:
boolean
-
cm:trigger_custom_incident(faction key
string,incident key
string,fire immediately
boolean,payload
string
) -
Forces an incident to trigger. A payload string fragment specifying the incident consequences must be supplied.
Parameters:
1
Faction key, from the
factionstable.2
Incident key, from the
dilemmastable.3
Set the incident to fire immediately.
4
Payload string. Check
missions.txtfor examples of how to structure a payload string.Returns:
nil
Example:
cm:trigger_custom_incident("troy_main_dan_achilles", "troy_main_test_incident", true, "payload{ faction_pooled_resource_transaction{resource troy_food;factor troy_resource_factor_faction;amount 5000;}"}");
-
cm:trigger_incident_with_targets(faction cqi
number,incident key
string,target faction cqi
string,secondary faction cqi
string,character cqi
string,military force cqi
string,region cqi
string,settlement cqi
string
) -
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_junctionstable in order to trigger.
A value of0may be supplied to omit a particular type of target.Parameters:
1
Command-queue index of the faction to which the incident is issued. This must be supplied.
2
Incident key, from the
incidentstable.3
Command-queue index of a target faction.
0may be specified to omit this target (and other target arguments following this one).4
Command-queue index of a second target faction. May be
0.5
Command-queue index of a target character. May be
0.6
Command-queue index of a target military force. May be
0.7
Command-queue index of a target region. May be
0.8
Command-queue index of a target settlement. May be
0.Returns:
nil
-
cm:toggle_incident_generation(can generateboolean) -
Sets whether the campaign director system can generate dilemmas or not.
Parameters:
1
can generate
Returns:
nil
-
cm:trigger_dilemma(stringfaction key, stringdilemma key,fire immediatelyboolean) -
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
stringFaction key.
2
stringDilemma key, from the dilemma table.
3
Set the incident to fire immediately.
Returns:
boolean
-
cm:trigger_custom_dilemma(faction key
string,dilemma key
string,first choice payload
string,second choice payload
string
) -
Triggers a custom dilemma with two choices, with the specified faction as the dilemma target.
Parameters:
1
Faction key, from the
factionstable.2
Dilemma key, from the
dilemmastable.3
Payload key for the first choice of the dilemma, from the
cdir_events_dilemma_payloadstable.4
Payload key for the second choice of the dilemma, from the
cdir_events_dilemma_payloadstable.Returns:
nil
-
cm:trigger_dilemma_with_targets(faction cqi
number,dilemma key
string,target faction cqi
number,secondary faction cqi
number,character cqi
number,military force cqi
number,region cqi
number,settlement cqi
number
) -
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_junctionstable in order to trigger.
A value of0may be supplied to omit a particular type of target.Parameters:
1
Command-queue index of the faction to which the dilemma is issued. This must be supplied.
2
Dilemma key, from the
dilemmastable.3
Command-queue index of a target faction.
0may be specified to omit this target (and other target arguments following this one).4
Command-queue index of a second target faction. May be
0.5
Command-queue index of a target character. May be
0.6
Command-queue index of a target military force. May be
0.7
Command-queue index of a target region. May be
0.8
Command-queue index of a target settlement. May be
0.Returns:
nil
-
cm:toggle_dilemma_generation(can generateboolean) -
Sets whether the campaign director system can generate dilemmas or not.
Parameters:
1
can generate
Returns:
nil
-
cm:trigger_intrigue(issuing faction
string,faction a key
string,faction b key
string,improve
boolean,exempt from cost
boolean
) -
Triggers an intrigue incident which improves or worsens diplomatic relations between two supplied factions.
Parameters:
1
Key of the faction issuing the intrigue, from the
factionsdatabase table.2
Key of the first target faction, from the
factionsdatabase table.3
Key of the second target faction, from the
factionsdatabase table.4
Specifies that the intrigue should improve rather than worsen diplomatic relations between the target factions.
5
Specifies that the intrigue should not cost influence points for issuing faction.
Returns:
nil
-
cm:enable_auto_generated_missions(enableboolean) -
Enable or disable non-scripted missions.
Parameters:
1
enable
Returns:
nil
-
cm:set_event_generation_enabled(enableboolean) -
Enables or disables random event generation by the campaign director system.
Parameters:
1
enable
Returns:
nil
-
cm:show_message_event(faction key
string,title loc key
string,primary loc key
string,secondary loc key
string,persistent
boolean,index
number
) -
Constructs and displays an event message.
Parameters:
1
Key of the faction to whom the event is targeted, from the
factionstable.2
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
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
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
Sets this event to be persistent instead of transient. Persistent events are saved to the event history which is accessible to the player.
6
Index indicating the type of event. This can be looked up by first finding a record in
event_feed_message_eventswhich relates to the event message being shown, then looking up the value in thecampaign_groupsfield of this record in thecampaign_group_member_criteria_values. This will provide one or more possible index values that may be used here.Returns:
nil
-
cm:show_configurable_message_event(faction key
string,title loc key
string,primary loc key
string,secondary loc key
string,index
number,param1
number,param2
number,param3
number
) -
Show a configurable message event with the specified title, primary detail and secondary detail to the specified faction. You can configure their behavior by editing the scripted_persistent_configurable_event record.
Parameters:
1
Key of the faction to whom the event is targeted, from the
factionstable.2
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
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
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
Index indicating the type of event. This can be looked up by first finding a record in
event_feed_message_eventswhich relates to the event message being shown, then looking up the value in thecampaign_groupsfield of this record in thecampaign_group_member_criteria_values. This will provide one or more possible index values that may be used here.6
[Optional] Number parameter for formatting.
7
[Optional] Number parameter for formatting.
8
[Optional] Number parameter for formatting.
Returns:
nil
-
cm:show_message_event_ruler_skill_competencies(faction key
string,power key
string,competency points
number
) -
Show a message event ruler_skill_competencies with the specified power name and competency points.
Parameters:
1
Key of the target faction, from the
factionstable.2
Power key.
3
Competency points.
Returns:
nil
-
cm:show_message_event_ruler_skill_surplus(faction key
string,power
string,position
string,region key
string,development points
number
) -
Show a message event ruler_skill_surplus with the specified power name and competency points.
Parameters:
1
Key of the target faction, from the
factionstable.2
Power key.
3
Court position key.
4
Region name, from the
campaign_map_regionsdatabase table.5
Development points.
Returns:
nil
-
cm:add_event_feed_event(event key
string,str_param1
string,str_param2
string,str_param3
string,param1
number,param2
number,param3
number,index
number
) -
Show an event feed message event by event_key with the specified params to the specified faction. The final parameter is the message event type index, used to pick message variants with different images and other details.
Parameters:
1
Key of the message event from the
event_feed_message_eventstable. It doesn't support all message event enums. Check the code before using if it's supported.2
[Optional] String parameter for formatting.
3
[Optional] String parameter for formatting.
4
[Optional] String parameter for formatting.
5
[Optional] Number parameter for formatting.
6
[Optional] Number parameter for formatting.
7
[Optional] Number parameter for formatting.
8
Index indicating the type of event. This can be looked up by first finding a record in
event_feed_message_eventswhich relates to the event message being shown, then looking up the value in thecampaign_groupsfield of this record in thecampaign_group_member_criteria_values. This will provide one or more possible index values that may be used here.Returns:
nil
-
cm:add_event_feed_message_new_victory_objective(faction key
string,category title key
string,category subtitle key
string,objective title key
string,description key
string,points
number
) -
Shows an event feed message of type
new_victory_objectiveornew_victory_objective_no_subcategory. The specific type is chosen based on whether stringsub_category_title_keyis empty.Parameters:
1
Key of the faction to whom the event is targeted, from the
factionstable.2
Localisation key for the event category title. This should be supplied in the full [table]_[field]_[key] localisation format, or can be a blank string.
3
Localisation key for the event category subtitle. This should be supplied in the full [table]_[field]_[key] localisation format, or can be a blank string.
4
Localisation key for the objective title. This should be supplied in the full [table]_[field]_[key] localisation format, or can be a blank string.
5
Localisation key for the objective description. This should be supplied in the full [table]_[field]_[key] localisation format, or can be a blank string.
6
Victory points reward.
Returns:
nil
-
cm:show_message_event_located(faction key
string,title loc key
string,primary loc key
string,secondary loc key
string,x
number,y
number,persistent
boolean,index
number
) -
Constructs and displays a event message with a zoom-to location.
Parameters:
1
Key of the faction to whom the event is targeted, from the
factionstable.2
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
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
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
Logical x co-ordinate of event target.
6
Logical y co-ordinate of event target.
7
Sets this event to be persistent instead of transient. Persistent events are saved to the event history which is accessible to the player.
8
Index indicating the type of event. This can be looked up by first finding a record in
event_feed_message_eventswhich relates to the event message being shown, then looking up the value in thecampaign_groupsfield of this record in thecampaign_group_member_criteria_values. This will provide one or more possible index values that may be used here.Returns:
nil
-
cm:suppress_all_event_feed_event_types(activate suppressionboolean) -
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_typeor 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 functionCampaignUI.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
activate suppression
Returns:
nil
-
cm:whitelist_event_feed_event_type(event typestring) -
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 theevent_feed_targeted_eventstable, by concatenating the values from theeventandtargetfields 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 withcm:suppress_all_event_feed_event_types.Parameters:
1
Event type, specified with a compound key from the
event_feed_targeted_eventstable.Returns:
nil
-
cm:event_feed_event_type_pending(event typestring) -
Returns whether any event messages of the supplied type are currently being blocked/withheld by event feed suppression. If this function returns
truefor a specified event type, then the withheld event messages may be shown by callingcm:whitelist_event_feed_event_typeto lift the suppression on that event type, or by callingcm:suppress_all_event_feed_event_typesto lift all suppression.Parameters:
1
Event type, specified with a compound key from the
event_feed_targeted_eventstable.Returns:
boolean
-
cm:disable_event_feed_events(should disable
boolean,category
string,subcategory
string,subcategory
string
) -
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
Disable the event messages specified by the supplied filters. Supply
falsehere to re-enable previously disabled event messages.2
Event feed category to block, from the
event_feed_categoriestable. Supply a blank string to not filter by category.3
Event feed subcategory to block, from the
event_feed_subcategoriestable. Supply a blank string to not filter by subcategory.4
Event feed subcategory to block, from the
event_feed_eventstable. Supply a blank string to not filter by event.Returns:
nil
-
cm:disable_all_event_feed_events(should disableboolean) -
Enable or disable all event feed events.
Parameters:
1
True to disable, false to enable
Returns:
nil
-
cm:set_ignore_end_of_turn_public_order(should disable
boolean,category
string,subcategory
string,subcategory
string
) -
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
Disable the event messages specified by the supplied filters. Supply
falsehere to re-enable previously disabled event messages.2
Event feed category to block, from the
event_feed_categoriestable. Supply a blank string to not filter by category.3
Event feed subcategory to block, from the
event_feed_subcategoriestable. Supply a blank string to not filter by subcategory.4
Event feed subcategory to block, from the
event_feed_eventstable. Supply a blank string to not filter by event.Returns:
nil
-
cm:add_restricted_building_level_record(building keystring) -
Disallow the construction of a specific building
See also the functioncm:remove_restricted_building_level_record.
See also the functioncm:add_restricted_building_level_record_for_faction.
See also the functioncm:remove_restricted_building_level_record_for_faction.Parameters:
1
building key
Returns:
nil
-
cm:remove_restricted_building_level_record(building keystring) -
Allow the construction of a specific building again
See also the functioncm:add_restricted_building_level_record.
See also the functioncm:add_restricted_building_level_record_for_faction.
See also the functioncm:remove_restricted_building_level_record_for_faction.Parameters:
1
building key
Returns:
nil
-
cm:add_restricted_building_level_record_for_faction(faction keystring,building keystring) -
Disallow the construction of a specific building for a specific faction
See also the functioncm:add_restricted_building_level_record.
See also the functioncm:remove_restricted_building_level_record.
See also the functioncm:remove_restricted_building_level_record_for_faction.Parameters:
1
faction key
2
building key
Returns:
nil
-
cm:remove_restricted_building_level_record_for_faction(faction keystring,building keystring) -
Allow the construction of a specific building again for a specific faction
See also the functioncm:add_restricted_building_level_record.
See also the functioncm:remove_restricted_building_level_record.
See also the functioncm:add_restricted_building_level_record_for_faction.Parameters:
1
faction key
2
building key
Returns:
nil
-
cm:instantly_build_building(slot keystring,building keystring, [should ignore costboolean]) -
Instantly construct a building with the specified key, in the specified settlement slot. The slot is specified by slot key.
Parameters:
1
Slot key. This is the region key, from the
campaign_map_regionsdatabase table, followed by a colon character and the slot number within the settlement, as a string.2
Key of the building to build, from the
building_levelsdatabase table.3
optional, default value=false
Sets whether the cost of the building construction should be ignored or not.
Returns:
nil
-
cm:instantly_downgrade_building(slot keystring,recoup costsboolean,silentboolean) -
Instantly downgrades the building in the speciifed settlement slot to the previous level. The slot is specified by slot key.
Parameters:
1
Slot key. This is the region key, from the
campaign_map_regionsdatabase table, followed by a colon character and the slot number within the settlement, as a string.2
Should the controlling faction recoup building costs from the downgrade.
3
Should the function notify other areas of the game that the downgrade is taking place. It is recommended to supply
truehere.Returns:
nil
-
cm:instantly_dismantle_foreign_slot_building(region key
string,faction key
string,foreign slot index
number
) -
Instantly dismantle the building in the foreign specified slot.
Parameters:
1
region key
2
faction key
3
foreign slot index
Returns:
nil
-
cm:region_slot_instantly_upgrade_building(slotslot,building keystring) -
Instantly upgrade the building in the specified slot to the specified building key.
See also thecampaign_managerfunctioncampaign_manager:instantly_upgrade_building_in_region.Parameters:
1
Settlement slot containing the building.
2
Building key, from the
building_levelstable.Returns:
nil
-
cm:region_slot_instantly_dismantle_building(slotslot,recoup costsboolean,silentboolean) -
Instantly dismantle the building in the specified slot. Slots keys are specified in the form
<region_key>:<slot_number>, where the slot number is a zero-based integer index.Parameters:
1
Settlement slot containing the building.
2
Should the controlling faction recoup building costs from the dismantle action.
3
Should the function notify other areas of the game that the dismantling is taking place. It is recommended to supply
truehere.Returns:
nil
-
cm:region_slot_instantly_repair_building(slotslot) -
Instantly repair the building in the specified slot. Slots keys are specified in the form
<region_key>:<slot_number>, where the slot number is a zero-based integer index.Parameters:
1
slot
Returns:
nil
-
cm:queue_building_construction(slot key
string,building key
string,turns override
number,ignore costs
boolean
) -
Orders the construction in the specified slot of a building with the specified key. The number of turns the building takes to construct can be overridden, as well as whether to spend resources/development points on the construction.
Parameters:
1
Slot key. This is the region key, from the
campaign_map_regionsdatabase table, followed by a colon character and the slot number within the settlement, as a string.2
Key of the building to build, from the
building_levelsdatabase table.3
Turns to complete override. If a positive integer is supplied then this overrides the number of turns for the building to complete. If
0is supplied then the building instantly completes. If-1is supplied, then the building construction duration is not overridden.4
Ignore the costs in resources and development points of the building construction, or not.
Returns:
nil
-
cm:queue_building_dismantle(slot keystring) -
Orders the dismantling of the building in the specified slot.
Parameters:
1
Slot key. This is the region key, from the
campaign_map_regionsdatabase table, followed by a colon character and the slot number within the settlement, as a string.Returns:
nil
-
cm:queue_building_repair(slot keystring,ignore costsboolean) -
Orders the repair of the building in the specified slot.
Parameters:
1
Slot key. This is the region key, from the
campaign_map_regionsdatabase table, followed by a colon character and the slot number within the settlement, as a string.2
Ignore the costs of the building construction, or not.
Returns:
nil
-
cm:add_building_to_settlement_queue(slotslot,building keystring) -
Orders the construction in the specified slot of a building with the specified key.
Parameters:
1
Target settlement slot.
2
Key of the building to build, from the
building_levelsdatabase table.Returns:
nil
-
cm:instant_set_building_health_percent(region keystring,building keystring,health percentnumber) -
Instantly set the health of a building.
Parameters:
1
Region key, from the
campaign_map_regionstable.2
Building level or chain key, from either the
building_levelsorbuilding_chainstables.3
New health value of building, expressed as a number from 0 to 100.
Returns:
nil
-
cm:set_building_can_repair(region keystring,building keystring,can repairboolean) -
Overrides if a building can repair.
Parameters:
1
Region key, from the
campaign_map_regionstable.2
Building level or chain key, from either the
building_levelsorbuilding_chainstables.3
Whether the building can repair or not
Returns:
nil
-
cm:get_building_from_building_chain(building chain keystring,levelnumber) -
Get the key of the building at the specified level from the specified building chain.
Parameters:
1
Building chain key, from the
building_chainsdatabase table.2
Level within chain to query. Valid values are 0-based, so a level of 0 specifies the first building in the chain.
Returns:
stringbuilding_levelsdatabase table.
-
cm:get_building_create_time(building keystring) -
Returns the number of turns the specified building would take to build.
Parameters:
1
Building key, from the
building_levelsdatabase table.Returns:
number
-
cm:get_building_conversion_cost_record_key(building keystring) -
Returns the convert resource cost key for the specified building. A blank string is returned if no resource cost has been specified in the
convert_resource_costfield for the building record in thebuilding_levelsdatabase table.Parameters:
1
Building key, from the
building_levelsdatabase table.Returns:
stringresource_costsdatabase table.
-
cm:get_building_repair_override_cost_record_key(building keystring) -
Get the repair override cost record key for the specified building. Nothing is returned if no resource cost has been specified in the
repair_resource_cost_overridefield for the building record in thebuilding_levelsdatabase table.Parameters:
1
Building key, from the
building_levelsdatabase table.Returns:
stringresource_costsdatabase table.
-
cm:is_building_excluded_from_corvee_labour(building keystring) -
Returns whether the supplied building is excluded from corvee labour. Excluded buildings will be present in the
building_level_corvee_labour_exclusionsdatabase table.Parameters:
1
Building key, from the
building_levelsdatabase table.Returns:
boolean
-
cm:complete_recruitment_and_contruction_in_region(region keystring) -
Instantly complete recruitment and construction in region.
Parameters:
1
Region key, from the
campaign_map_regionstable.Returns:
nil
-
cm:override_building_chain_display(building chain key
string,override chain key
string,region key
[string]
) -
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
Building chain key, from the
building_chainstable.2
Override building chain key, also from the
building_chainstable.3
optional, default value=nil
Region key, from the
campaign_map_regionstable.Returns:
nil
-
cm:add_building_to_force(force cqinumber,building keystring,operation was successfulboolean) -
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
Military force command-queue index value.
2
Building key, from the
building_levelstable.3
operation was successful
Returns:
nil
-
cm:remove_faction_foreign_slots_from_region(faction cqinumber,region cqinumber) -
Removes the specified foreign slot set from the target region, for the target faction.
Parameters:
1
Command-queue index value of the target faction.
2
Command-queue index value of the target region.
Returns:
nil
-
cm:add_settlement_model_override(Settlement keystring,Model namestring) -
Use a different model for a settlement.
Parameters:
1
Settlement key
2
Model name
Returns:
nil
-
cm:add_building_model_override(Slot keystring,Building keystring,Model namestring) -
Use a different model for a slot, generated slots are named: settlement_army-admin, settlement_culture, settlement_government, settlement_navy-admin, settlement_ordnance, settlement_minor, settlement_fortification.
Parameters:
1
Slot key
2
Building key
3
Model name
Returns:
nil
-
cm:remove_settlement_model_override(Settlement keystring) -
Use the default model for the settlement.
Parameters:
1
Settlement key
Returns:
nil
-
cm:remove_building_model_override(Slot keystring,Building keystring) -
Use the default model for the building.
Parameters:
1
Slot key
2
Building key
Returns:
nil
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(effect bundle keystring,faction keystring,turnsnumber) -
Apply an effect bundle to a faction for a number of turns, or indefinitely.
Parameters:
1
Effect bundle key, from the
effect_bundlestable.2
Faction key, from the
factionstable.3
Number of turns to apply the effect bundle for.
-1may be supplied to apply the effect indefinitely.Returns:
nil
-
cm:remove_effect_bundle(effect bundle keystring,faction keystring) -
Removes a previously-applied effect bundle from a faction.
Parameters:
1
Effect bundle key, from the
effect_bundlestable.2
Faction key, from the
factionstable.Returns:
nil
-
cm:apply_effect_bundle_to_character(effect bundle keystring,character cqinumber,turnsnumber) -
Apply an effect bundle to a character (by character cqi) for a number of turns (-1 turns means indefinitely).
Parameters:
1
Effect bundle key, from the
effect_bundlestable.2
Command-queue index of the character
3
Number of turns to apply the effect bundle for.
-1may be supplied to apply the effect indefinitely.Returns:
nil
-
cm:remove_effect_bundle_from_character(effect bundle keystring,character cqinumber) -
Remove a previously applied effect bundle from a character.
Parameters:
1
Effect bundle key, from the
effect_bundlestable.2
Command-queue index of the character
Returns:
nil
-
cm:apply_effect_bundle_to_force(effect bundle keystring,force cqinumber,turnsnumber) -
Apply an effect bundle to a military force for a number of turns, or indefinitely.
Parameters:
1
Effect bundle key, from the
effect_bundlestable.2
Command-queue index of the military force.
3
Number of turns to apply the effect bundle for.
-1may be supplied to apply the effect indefinitely.Returns:
nil
-
cm:remove_effect_bundle_from_force(effect bundle keystring,force cqinumber) -
Removes a previously-applied effect bundle from a military force.
Parameters:
1
Effect bundle key, from the
effect_bundlestable.2
Command-queue index of the military force.
Returns:
nil
-
cm:apply_effect_bundle_to_characters_force(effect bundle keystring,character cqinumber,turnsnumber) -
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
Effect bundle key, from the
effect_bundlestable.2
Command-queue index of the character commanding the military force.
3
Number of turns to apply the effect bundle for.
-1may be supplied to apply the effect indefinitely.Returns:
nil
-
cm:remove_effect_bundle_from_characters_force(effect bundle keystring,character cqinumber) -
Removes a previously-applied effect bundle from a military force, specified by its commanding character.
Parameters:
1
Effect bundle key, from the
effect_bundlestable.2
Command-queue index of the character commanding the military force.
Returns:
nil
-
cm:apply_effect_bundle_to_region(effect bundle keystring,region keystring,turnsnumber) -
Apply an effect bundle to a campaign map region for a number of turns, or indefinitely.
Parameters:
1
Effect bundle key, from the
effect_bundlestable.2
Region key, from the
campaign_map_regionstable.3
Number of turns to apply the effect bundle for.
-1may be supplied to apply the effect indefinitely.Returns:
nil
-
cm:remove_effect_bundle_from_region(effect bundle keystring,region keystring) -
Removes a previously-applied effect bundle from a campaign map region.
Parameters:
1
Effect bundle key, from the
effect_bundlestable.2
Region key, from the
campaign_map_regionstable.Returns:
nil
-
cm:apply_effect_bundle_to_province(effect bundle keystring,region keystring,turnsnumber) -
Apply an effect bundle to a campaign map province for a number of turns, or indefinitely.
Parameters:
1
Effect bundle key, from the
effect_bundlestable.2
Key of any region within the target province, from the
campaign_map_regionstable.3
Number of turns to apply the effect bundle for.
-1may be supplied to apply the effect indefinitely.Returns:
nil
-
cm:remove_effect_bundle_from_province(effect bundle keystring,region keystring) -
Removes a previously-applied effect bundle from a province.
Parameters:
1
Effect bundle key, from the
effect_bundlestable.2
Key of any region within the target province, from the
campaign_map_regionstable.Returns:
nil
-
cm:create_new_custom_effect_bundle(effect bundle keystring) -
Creates a new custom effect bundle from the specified effect bundle record.
Parameters:
1
Effect bundle key, from the
effect_bundlestable.Returns:
custom_effect_bundle
-
cm:apply_custom_effect_bundle_to_faction(effect bundle key
custom_effect_bundle,faction script interface
faction
) -
Apply a custom effect bundle to a faction. Replaces any existing effect bundle with the same record.
Parameters:
1
Effect bundle key, from the
effect_bundlestable.2
The faction script interface of the target faction.
Returns:
custom_effect_bundle
-
cm:apply_custom_effect_bundle_to_character(effect bundle key
custom_effect_bundle,character script interface
character
) -
Apply a custom effect bundle to a character. Replaces any existing effect bundle with the same record.
Parameters:
1
Effect bundle key, from the
effect_bundlestable.2
The script interface of the target character.
Returns:
custom_effect_bundle
-
cm:apply_custom_effect_bundle_to_force(effect bundle key
custom_effect_bundle,military force script interface
military_force
) -
Apply a custom effect bundle to a force. Replaces any existing effect bundle with the same record.
Parameters:
1
Effect bundle key, from the
effect_bundlestable.2
The script interface of the target military force.
Returns:
custom_effect_bundle
-
cm:apply_custom_effect_bundle_to_characters_force(effect bundle key
custom_effect_bundle,character script interface
character
) -
Apply a custom effect bundle to a characters force. Replaces any existing effect bundle with the same record.
Parameters:
1
Effect bundle key, from the
effect_bundlestable.2
The script interface of the target character.
Returns:
custom_effect_bundle
-
cm:apply_custom_effect_bundle_to_region(effect bundle key
custom_effect_bundle,region script interface
region
) -
Apply a custom effect bundle to a region. Replaces any existing effect bundle with the same record.
Parameters:
1
Effect bundle key, from the
effect_bundlestable.2
The region object.
Returns:
custom_effect_bundle
-
cm:apply_custom_effect_bundle_to_faction_province(effect bundle key
custom_effect_bundle,region script interface
region
) -
Apply a custom effect bundle to a faction province. Replaces any existing effect bundle with the same record.
Parameters:
1
Effect bundle key, from the
effect_bundlestable.2
The region object.
Returns:
custom_effect_bundle
-
cm:remove_effect_bundle_from_faction_province(effect bundle keystring,region script interfaceregion) -
Removes an effect bundle from a faction province.
Parameters:
1
Effect bundle key, from the
effect_bundlestable.2
The region object.
Returns:
nil
-
cm:force_diplomacy_new(source faction
string,target faction
string,bitmask
number,can offer
boolean,can accept
boolean
) -
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>orculture:<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:
The function
Diplomacy Type Mask Value
trade agreement 2^0hard military access 2^1cancel hard military access 2^2military alliance 2^3regions 2^4technology 2^5state gift 2^6payments 2^7vassal 2^8subject 2^9peace 2^10war 2^11join war 2^12break trade 2^13break alliance 2^14hostages 2^15marriage 2^16non aggression pact 2^17soft military access 2^18cancel soft military access 2^19defensive alliance 2^20client state 2^21form confederation 2^22break non aggression pact 2^23break soft military access 2^24break defensive alliance 2^25break vassal 2^26break subject 2^27break client state 2^28state gift unilateral 2^29diplomatic gift 2^30single barters 2^31barter agreements 2^32cancel barters 2^33dominance 2^34all (2^35 - 1)campaign_manager:force_diplomacyon thecampaign_managerinterface wraps this function, providing a more useable interface and console output. It's recommended to call that function rather than directly calling this one.Parameters:
1
Specifier that specifies one or more source factions.
2
Specifier that specifies one or more target factions.
3
Bitmask.
4
Sets whether the source faction(s) can to offer deals of this diplomacy type to the target faction(s).
5
Sets whether the target faction(s) can accept deals of this diplomacy type from the source faction(s).
Returns:
nil
-
cm:force_diplomacy_new_s(source faction
string,target faction
string,bitmask
string,can offer
boolean,can accept
boolean
) -
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>orculture:<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:
In contrast to
Diplomacy Type Mask Value
trade agreement 2^0hard military access 2^1cancel hard military access 2^2military alliance 2^3regions 2^4technology 2^5state gift 2^6payments 2^7vassal 2^8subject 2^9peace 2^10war 2^11join war 2^12break trade 2^13break alliance 2^14hostages 2^15marriage 2^16non aggression pact 2^17soft military access 2^18cancel soft military access 2^19defensive alliance 2^20client state 2^21form confederation 2^22break non aggression pact 2^23break soft military access 2^24break defensive alliance 2^25break vassal 2^26break subject 2^27break client state 2^28state gift unilateral 2^29diplomatic gift 2^30single barters 2^31barter agreements 2^32cancel barters 2^33dominance 2^34all (2^35 - 1)cm:force_diplomacy_new, the bitmask forcm:force_diplomacy_new_sis astringto prevent number overflows.
The functioncampaign_manager:force_diplomacyon thecampaign_managerinterface wraps this function, providing a more useable interface and console output. It's recommended to call that function rather than directly calling this one.Parameters:
1
Specifier that specifies one or more source factions.
2
Specifier that specifies one or more target factions.
3
Bitmask.
4
Sets whether the source faction(s) can to offer deals of this diplomacy type to the target faction(s).
5
Sets whether the target faction(s) can accept deals of this diplomacy type from the source faction(s).
Returns:
nil
-
cm:force_declare_war(attacking faction key
string,target faction key
string,invite attacker allies
boolean,invite defender allies
boolean,forced choice
boolean
) -
Forces one faction to declare war on another.
Parameters:
1
Faction key of the attacking faction, from the
factionstable.2
Faction key of the target faction, from the
factionstable.3
Allows factions allied with the attacker to choose whether to join.
4
Allows factions allied with the defender to choose whether to join.
5
attacking faction will have lower treachery penalties if they have any treaties with target faction if this is true
Returns:
nil
-
cm:force_make_vassal(vassalising faction keystring,vassal faction keystring,forced choiceboolean) -
Force one faction to vassalise another faction.
Parameters:
1
Key of the faction which will become the master, from the
factionstable.2
Key of the faction which will become the vassal, from the
factionstable.3
Vassalising faction will have lower treachery penalties if they are at war with vassal faction if this is true
Returns:
nil
-
cm:force_make_subject(subjugating faction keystring,subject faction keystring,forced choiceboolean) -
Force one faction to subjugate another faction.
Parameters:
1
Key of the faction which will become the sovereign, from the
factionstable.2
Key of the faction which will become the subject, from the
factionstable.3
subjugating faction will have lower treachery penalties if they are at war with subject faction if this is true
Returns:
nil
-
cm:force_alliance(first faction key
string,second faction key
string,is military alliance
boolean,forced choice
boolean
) -
Force two factions to become defensive or military allies.
Parameters:
1
Faction key of the first faction, from the
factionstable.2
Faction key of the second faction, from the
factionstable.3
Specifies whether the alliance should be a military alliance. If
falseis supplied then the alliance is defensive.4
first faction will have lower treachery penalties if they are at war with second faction if this is true
Returns:
nil
-
cm:force_break_alliance(first faction keystring,second faction keystring,force choiceboolean) -
Force two factions to break their alliance.
Parameters:
1
First allied faction key, from the
factionsdatabase table.2
Second allied faction key, from the
factionsdatabase table.3
Spoofs to the diplomacy system that the choice to break the alliance was forced on the first faction e.g. as the lesser of two treacheries. This lessens the diplomatic penalty it incurs with the second faction.
Returns:
nil
-
cm:force_grant_military_access(granting faction key
string,recipient faction key
string,is hard access
boolean,forced choice
boolean
) -
Force one faction to grant another faction military access to its territory.
Parameters:
1
Faction key of the granting faction, from the
factionstable.2
Faction key of the recipient faction, from the
factionstable.3
Indicates whether this should be hard military access. This concept is currently unused.
4
granting faction will have lower treachery penalties if they are at war with recipient faction if this is true
Returns:
nil
-
cm:force_make_peace(first faction keystring,second faction keystring,forced choiceboolean) -
Forces peace between two warring factions.
Parameters:
1
Faction key of the first faction, from the
factionstable.2
Faction key of the second faction, from the
factionstable.3
first faction will have lower treachery penalties if the war's duration is too low, if this is true
Returns:
nil
-
cm:force_confederation(proposing faction keystring,target faction keystring) -
Forces a proposing faction to subsume a target faction into its confederation.
Parameters:
1
Faction key of the proposing faction, from the
factionstable.2
Faction key of the target faction, from the
factionstable. This faction will be subsumed into the confederation.Returns:
nil
-
cm:force_make_trade_agreement(first faction keystring,second faction keystring) -
Forces a trade agreement between two specified factions. If no agreement is possible then nothing will happen.
Parameters:
1
Faction key of the first faction, from the
factionstable.2
Faction key of the second faction, from the
factionstable.Returns:
nil
-
cm:make_diplomacy_available(first faction keystring,second faction keystring) -
Makes diplomacy available between two factions, as if they had discovered each other on the campaign map.
Parameters:
1
Faction key of the first faction, from the
factionstable.2
Faction key of the second faction, from the
factionstable.Returns:
nil
-
cm:faction_offers_peace_to_other_faction(proposing faction keystring,target faction keystring) -
Compels one faction to offer peace to another faction that it's at war with. The target faction may decline.
Parameters:
1
Faction key of the first faction, from the
factionstable.2
Faction key of the second faction, from the
factionstable.Returns:
nil
-
cm:faction_allow_trading(factionfaction, booleanshould_allow) -
Enable/Disable trading for faction.
Parameters:
1
faction
2
booleanshould_allow
Returns:
nil
-
cm:steal_barter_agreement(originator faction key
string,target faction key
string,stealing faction key
string,agreement index
number
) -
Steal the barter agreement of two other factions.
Parameters:
1
Originator faction key, from the
factionsdatabase table.2
Target faction key, from the
factionsdatabase table.3
Stealing faction key, from the
factionsdatabase table.4
Barter agreement index.
Returns:
nil
-
cm:cancel_barter_agreement(originator faction key
string,target faction key
string,agreement index
number
) -
Break barter agreement between two factions.
Parameters:
1
Originator faction key, from the
factionsdatabase table.2
Target faction key, from the
factionsdatabase table.3
Barter agreement index.
Returns:
nil
-
cm:set_trespassing_diplomatic_penalty_enabled(enableboolean) -
Enable/Disable the diplomatic penalty for trespassing.
Parameters:
1
enable
Returns:
nil
-
cm:apply_dilemma_diplomatic_bonus(faction a keystring,faction a keystring,bonus valuenumber) -
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
-6and+6, each integer value of which corresponds to a change type (fromPENALTY_XXXLARGE(-6) toBONUS_XXXLARGE(+6)) which carries a diplomatic attitude modifier that is actually applied.Parameters:
1
First faction key.
2
Second faction key.
3
Bonus value (
-6to+6).Returns:
nil
-
cm:add_event_restricted_unit_record(unit keystring, [tooltip keystring]) -
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
Unit key, from the
main_unitstable.2
optional, default value=nil]
stringtooltip key, Key of localised text in full [table]_[field]_[keyKey of localised text in full [table]_[field]_[key] format to show as a tooltip on the restricted unit icon. This can be omitted.
Returns:
nil
-
cm:remove_event_restricted_unit_record(unit keystring) -
Removes a restriction previously added with
cm:add_event_restricted_unit_record.Parameters:
1
Unit key, from the
main_unitstable.Returns:
nil
-
cm:add_event_restricted_unit_record_for_faction(unit keystring,faction keystring, [tooltip keystring]) -
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
Unit key, from the
main_unitstable.2
Faction key, from the
factionstable.3
optional, default value=nil]
stringtooltip key, Key of localised text in full [table]_[field]_[keyKey of localised text in full [table]_[field]_[key] format to show as a tooltip on the restricted unit icon. This can be omitted.
Returns:
nil
-
cm:remove_event_restricted_unit_record_for_faction(unit keystring,faction keystring) -
Removes a restriction previously added with
cm:add_event_restricted_unit_record_for_faction.Parameters:
1
Unit key, from the
main_unitstable.2
Faction key, from the
factionstable.Returns:
nil
-
cm:add_event_restricted_building_record(building keystring, [tooltip keystring]) -
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
Building key, from the
building_levelstable.2
optional, default value=nil]
stringtooltip key, Key of localised text in full [table]_[field]_[keyKey of localised text in full [table]_[field]_[key] format to show as a tooltip on the restricted building icon. This can be omitted.
Returns:
nil
-
cm:remove_event_restricted_building_record(building keystring) -
Removes a restriction previously added with
cm:add_event_restricted_building_record.Parameters:
1
Building key, from the
building_levelstable.Returns:
nil
-
cm:add_event_restricted_building_record_for_faction(building key
string,faction key
string,tooltip key
[string]
) -
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
Building key, from the
building_levelstable.2
Faction key, from the
factionstable.3
optional, default value=nil]
stringtooltip key, Key of localised text in full [table]_[field]_[keyKey of localised text in full [table]_[field]_[key] format to show as a tooltip on the restricted building icon. This can be omitted.
Returns:
nil
-
cm:remove_event_restricted_building_record_for_faction(building keystring,faction keystring) -
Removes a restriction previously added with
cm:add_event_restricted_building_record_for_faction.Parameters:
1
Building key, from the
building_levelstable.2
Faction key, from the
factionstable.Returns:
nil
-
cm:add_event_restricted_building_chain_record_for_faction(building chain key
string,faction key
string,tooltip key
[string]
) -
Adds a restriction preventing buildings form a specified building chain 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
Building chain key, from the
building_chainstable.2
Faction key, from the
factionstable.3
optional, default value=nil]
stringtooltip key, Key of localised text in full [table]_[field]_[keyKey of localised text in full [table]_[field]_[key] format to show as a tooltip on the restricted building icon. This can be omitted.
Returns:
nil
-
cm:remove_event_restricted_building_chain_record_for_faction(building chain key
string,faction key
string
) -
Removes a restriction previously added with
cm:add_event_restricted_building_chain_record_for_faction.Parameters:
1
Building chain key, from the
building_chainstable.2
Faction key, from the
factionstable.Returns:
nil
-
cm:add_event_restricted_building_record_with_manual_conversion(building key
string,tooltip key
[string]
) -
Adds a restriction preventing a specified building from being a construction option for any faction, but sets them to be manualy converted for human factions if they acquire a region with them in it.
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
Building key, from the
building_levelstable.2
optional, default value=nil]
stringtooltip key, Key of localised text in full [table]_[field]_[keyKey of localised text in full [table]_[field]_[key] format to show as a tooltip on the restricted building icon. This can be omitted.
Returns:
nil
-
cm:remove_event_restricted_building_record_with_manual_conversion(building keystring) -
Removes a restriction previously added with
cm:add_event_restricted_building_record.Parameters:
1
Building key, from the
building_levelstable.Returns:
nil
-
cm:add_event_restricted_building_record_for_faction_with_manual_conversion(building key
string,faction key
string,tooltip key
[string]
) -
Adds a restriction preventing a specified building from being a construction option for a specified faction, but sets them to be manualy converted for human factions if they acquire a region with them in it.
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
Building key, from the
building_levelstable.2
Faction key, from the
factionstable.3
optional, default value=nil]
stringtooltip key, Key of localised text in full [table]_[field]_[keyKey of localised text in full [table]_[field]_[key] format to show as a tooltip on the restricted building icon. This can be omitted.
Returns:
nil
-
cm:remove_event_restricted_building_record_for_faction_with_manual_conversion(building key
string,faction key
string
) -
Removes a restriction previously added with
cm:add_event_restricted_building_record_for_faction_with_manual_conversion.Parameters:
1
Building key, from the
building_levelstable.2
Faction key, from the
factionstable.Returns:
nil
-
cm:add_event_restricted_building_chain_record_for_faction_with_manual_conversion(building chain key
string,faction key
string,tooltip key
[string]
) -
Adds a restriction preventing buildings form a specified building chain from being a construction option for a specified faction, but sets them to be manualy converted for human factions if they acquire a region with them in it.
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
Building chain key, from the
building_chainstable.2
Faction key, from the
factionstable.3
optional, default value=nil]
stringtooltip key, Key of localised text in full [table]_[field]_[keyKey of localised text in full [table]_[field]_[key] format to show as a tooltip on the restricted building icon. This can be omitted.
Returns:
nil
-
cm:remove_event_restricted_building_chain_record_for_faction_with_manual_conversion(building chain key
string,faction key
string
) -
Removes a restriction previously added with
cm:add_event_restricted_building_chain_record_for_faction_with_manual_conversion.Parameters:
1
Building chain key, from the
building_chainstable.2
Faction key, from the
factionstable.Returns:
nil
-
cm:add_event_restricted_ancillary_type_equip_restriction_for_faction(ancillary key
string,faction key
string,tooltip key
[string]
) -
Adds a restriction record for an ancillary type for a faction, preventing that faction from equipping an ancillary of that type.
Parameters:
1
Ancillary key, from the
ancillariesdatabase table.2
Faction key, from the
factionsdatabase table.3
optional, default value=nil]
stringtooltip key, Key of localised text in full [table]_[field]_[keyKey of localised text in full [table]_[field]_[key] format to show as a tooltip on the restricted ancillary icon. This can be omitted.
Returns:
nil
-
cm:remove_event_restricted_ancillary_type_equip_restriction_for_faction(ancillary key
string,faction key
string
) -
Removes a restriction record for an ancillary type for a faction previously added with
cm:add_event_restricted_ancillary_type_equip_restriction_for_faction, allowing that faction to equip an ancillary of that type again.Parameters:
1
Ancillary key, from the
ancillariesdatabase table.2
Faction key, from the
factionsdatabase table.Returns:
nil
-
cm:add_event_restricted_province_initiative_record_for_faction(initiative key
string,faction key
string,tooltip key
[string]
) -
Adds a restriction record for a province initiative for a faction, preventing that faction from enacting that province initiative.
Parameters:
1
Province initiative key, from the
provincial_initiative_recordsdatabase table.2
Faction key, from the
factionsdatabase table.3
optional, default value=nil]
stringtooltip key, Key of localised text in full [table]_[field]_[keyKey of localised text in full [table]_[field]_[key] format to show as a tooltip on the restricted province initiative. This can be omitted.
Returns:
nil
-
cm:remove_event_restricted_province_initiative_record_for_faction(initiative key
string,faction key
string
) -
Removes a province initiative restriction record previously added with
cm:add_event_restricted_province_initiative_record_for_faction, allowing that faction to use the specified province initiative again.Parameters:
1
Province initiative key, from the
provincial_initiative_recordsdatabase table.2
Faction key, from the
factionsdatabase table.Returns:
nil
-
cm:add_event_restricted_province_initiative_record_for_province_for_faction(initiative key
string,province key
string,faction key
string,tooltip key
[string]
) -
Adds a restriction record for a province initiative for a faction, for a specified province, preventing that faction from enacting the province initiative within that province.
Parameters:
1
Province initiative key, from the
provincial_initiative_recordsdatabase table.2
Province key, from the
provincesdatabase table.3
Faction key, from the
factionsdatabase table.4
optional, default value=nil]
stringtooltip key, Key of localised text in full [table]_[field]_[keyKey of localised text in full [table]_[field]_[key] format to show as a tooltip on the restricted province initiative. This can be omitted.
Returns:
nil
-
cm:remove_event_restricted_province_initiative_record_for_province_for_faction(initiative key
string,province key
string,faction key
string
) -
Removes a province initiative restriction record previously added with
cm:add_event_restricted_province_initiative_record_for_province_for_faction, allowing that faction to use the specified province initiative within the specified province again.Parameters:
1
Province initiative key, from the
provincial_initiative_recordsdatabase table.2
Province key, from the
provincesdatabase table.3
Faction key, from the
factionsdatabase table.Returns:
nil
-
cm:lock_technology(faction keystring,technology keystring) -
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
Faction key, from the
factionstable.2
Technology key, from the
technologiestable.Returns:
nil
-
cm:unlock_technology(faction keystring,technology keystring) -
Removes a lock previously placed with
cm:lock_technology.Parameters:
1
Faction key, from the
factionstable.2
Technology key, from the
technologiestable.Returns:
nil
-
cm:instantly_complete_ongoing_research_for_faction(faction key
string,should_only_first_ongoing_research
[boolean]
) -
Instantly complete the ongoing research for given faction
Parameters:
1
Faction key, from the
factionstable.2
optional, default value=false
If true, it will complete only the first ongoing research.
Returns:
nil
-
cm:disable_movement_for_character(character lookupstring) -
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_factionorcm: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
Character lookup string - see
Character Lookupsfor more information.Returns:
nil
-
cm:disable_movement_for_faction(faction keystring) -
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_factionorcm: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
Faction key, from the
factionstable.Returns:
nil
-
cm:enable_movement_for_character(character lookupstring) -
Re-enables movement for a specified character after it has been disabled with
cm:disable_movement_for_characterorcm:disable_movement_for_faction.Parameters:
1
Character lookup string - see
Character Lookupsfor more information.Returns:
nil
-
cm:enable_movement_for_faction(faction keystring) -
Re-enables movement for every character in the specified faction after it has been disabled with
cm:disable_movement_for_characterorcm:disable_movement_for_faction.Parameters:
1
Faction key, from the
factionstable.Returns:
nil
-
cm:disable_pathfinding_restriction(idnumber) -
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
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:
nil
-
cm:add_restricted_unit_upgrade(source_unit_keystring,target_unit_keystring) -
Restricts the supplied unit by key from performing unit upgrade to the supplied unit by key.
Parameters:
1
Base unit to be upgraded.
2
Target unit to be upgraded to.
Returns:
nil
-
cm:remove_restricted_unit_upgrade(source_unit_keystring,target_unit_keystring) -
Re-enables the supplied unit by key to performing unit upgrade to the supplied unit by key, after it has been disabled with
cm:add_restricted_unit_upgrade.Parameters:
1
Base unit to be upgraded.
2
Target unit to be upgraded to.
Returns:
nil
-
cm:disallow_army_occupation_decision(force cqinumber,occupation_decisionstring) -
Disallows a specific army from performing a specific occupation decision.
Parameters:
1
Command-queue index value for the military force.
2
key from the
settlement_occupation_optionstable.Returns:
nil
-
cm:remove_forced_occupation_decision_restrictions(force cqinumber) -
Removes any occupation decision restrictions previously imposed with
cm:disallow_army_occupation_decision.Parameters:
1
Command-queue index value for the military force.
Returns:
nil
-
cm:disallow_faction_occupation_decision(faction script interfacefaction,occupation_decisionstring) -
Disallows the faction's armies from performing a specific occupation decision.
Parameters:
1
The faction script interface of the target faction.
2
key from the
settlement_occupation_optionstable.Returns:
nil
-
cm:remove_forced_occupation_decision_restrictions_for_faction(faction script interfacefaction) -
Removes any occupation decision restrictions previously imposed with
cm:disallow_faction_occupation_decision.Parameters:
1
The faction script interface of the target faction.
Returns:
nil
Rituals are faction-level spells that underpin a variety of racial effects. A list of all rituals in the game can be found in the rituals database table.
-
cm:perform_ritual(performing faction key
string,target faction key
string,ritual key
string,ritual chain key
string
) -
Perform a ritual for a faction. The ritual must be available and valid for the action to succeed.
Parameters:
1
Faction key of the faction performing the ritual, from the
factionstable.2
Faction key of the target faction of the ritual, from the
factionstable. An emptystringmay be supplied, in which case the performing faction is the target.3
Ritual key, from the
ritualsdatabase table.4
Ritual chain key, from the
ritual_chainsdatabase table.Returns:
nil
-
cm:rollback_linked_ritual_chain(ritual chain keystring, numberstage) -
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
Ritual chain key, from the
campaign_group_ritual_chainstable.2
numberStage number.
Returns:
nil
-
cm:set_ritual_unlocked(faction cqinumber,ritual keystring,unlockboolean) -
Locks or unlocks a ritual for the specified faction.
Parameters:
1
Command-queue index value for the target faction.
2
Ritual key, from the
ritualsdatabase table.3
Unlock the ritual.
Returns:
nil
-
cm:set_ritual_chain_unlocked(faction cqinumber,ritual chain keystring,unlockboolean) -
Locks or unlocks a chain of rituals for the specified faction.
Parameters:
1
Command-queue index value for the target faction.
2
Ritual chain key, from the
ritual_chainsdatabase table.3
Unlock the ritual chain.
Returns:
nil
-
cm:set_ritual_in_chain_unlocked(faction cqi
number,ritual key
string,ritual chain key
string,unlock
boolean
) -
Locks or unlocks a ritual in a chain for the specified faction.
Parameters:
1
Command-queue index value for the target faction.
2
Ritual key, from the
ritualsdatabase table.3
Ritual chain key, from the
ritual_chainsdatabase table.4
Unlock the ritual chain.
Returns:
nil
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(faction keystring,changenumber) -
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
Faction key, from the
factionstable.2
Value to modify slaves by.
Returns:
nil
-
cm:modify_faction_slaves_in_a_faction_province(region keystring,changenumber) -
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
Region key, from the
campaign_map_regionstable.2
Value to modify slaves by.
Returns:
nil
-
cm:faction_economics_recalculate_background_income(faction keystring) -
Force a recalculation of the background income for the specified faction. This is done in order for the AI to know how much background income does it has.
Parameters:
1
Faction key, from the
factionstable.Returns:
nil
-
cm:province_spawn_pooled_resource(province keystring,resource keystring) -
Spawn pooled_resource in province. Clamped to pool bounds.
Parameters:
1
Province key, from the
provincestable.2
Pooled resource key, from the
pooled_resourcestable.Returns:
nil
-
cm:consume_pooled_resource(province keystring,resource keystring,amountnumber) -
Consumes the specified pooled resource from the specified province, reducing the total amount avaliable in the deposit.
Parameters:
1
Province key, from the
provincestable.2
Pooled resource key, from the
pooled_resourcestable.3
Amount of resource to add. This value CANNOT be negative.
Returns:
nil
-
cm:faction_add_pooled_resource(faction keystring,resource keystring,factor keystring,amountnumber) -
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
Faction key, from the
factionstable.2
Pooled resource key, from the
pooled_resourcestable.3
Change factor key, from the
pooled_resource_factorstable.4
Amount of resource to add. This value can be negative.
Returns:
nil
-
cm:faction_apply_resource_transaction(factionfaction,costcustom_resource_cost) -
Apply the specified resource cost transaction to the supplied faction
Parameters:
1
Faction to apply the resoruce cost
2
Resource cost
Returns:
nil
-
cm:faction_add_post_battle_looted_resource(faction key
string,resource key
string,factor key
string,amount
number,should_apply_resource_transaction
[boolean]
) -
Add the specified amount to the specified pool for the loot in pending pattle participant. (must have active pending battle). Amount can be negative. Optionally (yes - by default) apply a resource transaction on that amount.
Parameters:
1
Faction key, from the
factionstable.2
Pooled resource key, from the
pooled_resourcestable.3
Change factor key, from the
pooled_resource_factorstable.4
Amount of resource to add. This value can be negative.
5
optional, default value=true
Whether to apply the resource transaction.
Returns:
nil
-
cm:faction_set_free_embed_informants(faction keystring,informantsnumber) -
Sets a new value for the number of available informants in a faction.
Parameters:
1
Faction key, from the
factionsdatabase table.2
Number of informants.
Returns:
nil
-
cm:faction_add_post_battle_motivation_change(character cqinumber,amountnumber) -
Tells a pending battle object that there has been motivation changes to a character. Used to display to the user, doesn't actually change anything. Only works on characters in the currently pending battle.
Parameters:
1
Command queue index of the character whose motivation is changed
2
The amount of the change. Positive or negative value.
Returns:
nil
-
cm:faction_set_food_factor_multiplier(faction keystring,food factor keystring,multipliernumber) -
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
Faction key, from the
factionstable.2
Food factor key, from the
food_factorstable.3
Multiplier.
Returns:
nil
-
cm:faction_set_food_factor_value(faction keystring,food factor keystring,modifiernumber) -
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
Faction key, from the
factionstable.2
Food factor key, from the
food_factorstable.3
Modifier.
Returns:
nil
-
cm:faction_mod_food_factor_value(faction keystring,food factor keystring,modifiernumber) -
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
Faction key, from the
factionstable.2
Food factor key, from the
food_factorstable.3
Modifier.
Returns:
nil
-
cm:notify_hatshepsut_expedition_started(faction keystring,realm final destinationstring) -
Notifies the game that a Hatshepsut expedition has started for the specified faction.
Parameters:
1
Faction key, from the
factionstable.2
Realm final destination.
Returns:
nil
-
cm:notify_hatshepsut_expedition_resource_cashed_out(faction key
string,resource key
string,amount
number
) -
Notifies the game that a Hatshepsut expedition is cashing out.
Parameters:
1
Faction key, from the
factionstable.2
Resource key, from the
pooled_resourcesdatabase table.3
Amount of resource.
Returns:
nil
-
cm:notify_khufu_stage_construction_started(faction keystring,wonder keystring,stage keystring) -
Notifies the game that construction has started on a Khufu wonder stage.
Parameters:
1
Faction key, from the
factionstable.2
Wonder key.
3
Stage key.
Returns:
nil
-
cm:notify_khufu_stage_construction_completed(faction keystring,wonder keystring,stage keystring) -
Notifies the game that construction has completed on a Khufu wonder stage.
Parameters:
1
Faction key, from the
factionstable.2
Wonder key.
3
Stage key.
Returns:
nil
-
cm:notify_khufu_wonder_attacked(attacking faction key
string,wonder key
string,wonder owner won
boolean,is attacker player
boolean
) -
Notifies the game that a Khufu wonder has been attacked.
Parameters:
1
Attacking faction key, from the
factionstable.2
Wonder key.
3
Indicates that the wonder owner win the battle.
4
Indicates that the attacking faction was controlled by a player.
Returns:
nil
-
cm:notify_muwatalli_token_of_gratitude_gained(faction keystring,action keystring) -
Notifies the game that a Muwatalli token of gratitude has been gained by a faction.
Parameters:
1
Faction key, from the
factionstable.2
Action key.
Returns:
nil
-
cm:notify_tudhaliya_title_assigned_to_prince(faction keystring,title keystring) -
Notifies the game that a Tudhaliya title has been assigned to a Prince.
Parameters:
1
Faction key of the prince, from the
factionsdatabase table.2
Tudhaliya title key, from the
ancillariesdatabase table.Returns:
nil
-
cm:apply_prince_battle_diplomatic_bonus(master faction key
string,vassal faction key
string,battle won
boolean
) -
Applies a Tudhaliya prince battle diplomatic bonus to the specified vassal faction.
Parameters:
1
Master or sovereign faction key, from the
factionsdatabase table.2
Vassal or subject faction key, from the
factionsdatabase table.3
Indicates that the recently-fought battle was won.
Returns:
nil
-
cm:apply_prince_idle_diplomatic_bonus(master faction key
string,vassal faction key
string,in vassal territory
boolean
) -
Applies a Tudhaliya prince idling diplomatic bonus to the specified vassal faction.
Parameters:
1
Master or sovereign faction key, from the
factionsdatabase table.2
Vassal or subject faction key, from the
factionsdatabase table.3
Indicates that the Prince was idling in the vassal's territory.
Returns:
nil
-
cm:notify_legitimacy_war_updated(faction key
string,ruling faction key
string,state
string,start turn
number,legitimacy
number,ruler legitimacy
number,attitude
number,pretenders
string,political state
string
) -
Notifies the game about an update in the status of a legitimacy war.
Parameters:
1
Faction key, from the
factionsdatabase table.2
Ruling faction key, from the
factionsdatabase table.3
Update state.
4
Start turn of war.
5
Faction legitimacy value.
6
Ruling faction legitimacy value.
7
Attitude value towards ruling faction.
8
Comma-separated list of pretender faction keys.
9
Political state id.
Returns:
nil
-
cm:notify_legitimacy_war_ended(ruling faction key
string,start turn
number,war length
number,political state
string
) -
Notifies the game that a legitimacy war has ended.
Parameters:
1
New ruling faction key, from the
factionsdatabase table.2
Start turn of war.
3
Length of war in turns.
4
Political state id.
Returns:
nil
-
cm:notify_legitimacy_special_ancillary_equipped_and_available(faction key
string,equipped ancillaries
string,political state
string
) -
Notifies the game about special legitimacy ancillaries that are equipped or that are available for faction.
Parameters:
1
Ruling faction key, from the
factionsdatabase table.2
Commas-separated string of ancillary keys equipped by the faction.
3
Political state id.
Returns:
nil
-
cm:notify_crown_power_used(ruling faction keystring,powerstring,political statestring) -
Notifies the game that a crown power has been used.
Parameters:
1
Ruling faction key, from the
factionsdatabase table.2
Crown power used.
3
Political state id.
Returns:
nil
-
cm:notify_court_action_used(faction keystring,action namestring,action subnamestring) -
Notifies the game that a court action has been used.
Parameters:
1
Faction key, from the
factionsdatabase table.2
Court action name.
3
Court action subname.
Returns:
nil
-
cm:notify_court_position_gained(faction keystring,positionstring) -
Notifies the game that a court position has been gained by a faction.
Parameters:
1
Faction key, from the
factionsdatabase table.2
Court position name.
Returns:
nil
-
cm:set_new_civilization_level(new levelstring) -
Sets a new campaign-wide civilization level. Currently-valid civilisation levels area
"collapse","crisis","prosperity","custom_1", ..."custom_12".Parameters:
1
new level
Returns:
nil
-
cm:notify_ambition_status_changed(faction keystring,ambition keystring,new statusstring) -
Notifies the game that the status of an ambition has changed. Valid status values are currently
"picked","completed","cancelled","expired"and"failed".Parameters:
1
Faction key, from the
factionsdatabase table.2
Ambition key, from the
missionsdatabase table.3
New status.
Returns:
nil
-
cm:notify_ambition_list_displayed(faction keystring,ambitionsstring) -
Notifies the game that an ambition list is being displayed for a faction.
Parameters:
1
Faction key, from the
factionsdatabase table.2
Comma-separated list of ambitions being displayed. Each ambition is a key from the
missionsdatabase table.Returns:
nil
-
cm:set_is_sacred_egyptian_region(region keystring,is sacredboolean) -
Sets whether a region is a sacred egyptian region.
Parameters:
1
Region key, from the
regionstable.2
Is the region a sacred egyptian region.
Returns:
nil
-
cm:set_is_sacred_hatti_region(region keystring,is sacredboolean) -
Set whether a region is a sacred hatti region.
Parameters:
1
Region key, from the
regionstable.2
Is the region a sacred hatti region.
Returns:
nil
-
cm:add_realm(realm keystring) -
Inform the model of the existence of a realm with the supplied key.
Parameters:
1
Realm key.
Returns:
nil
-
cm:set_region_realm(region keystring,realm keystring) -
Sets the realm associated with a region.
Parameters:
1
Region key, from the
regionstable.2
Realm key.
Returns:
nil
-
cm:add_god_to_realm(realm keystring,god namestring,icon pathstring) -
Add a god to the specified realm.
Parameters:
1
Realm key.
2
God localised name key. Localisation key for the title. This should be supplied in the full [table]_[field]_[key] localisation format.
3
God icon path, from the working data folder.
Returns:
nil
-
cm:add_overriden_god_for_region(realm keystring,god namestring,icon pathstring) -
Add a god override for a specific region, replacing any gods associated with the region's realm.
Parameters:
1
Realm key.
2
God localised name key. Localisation key for the title. This should be supplied in the full [table]_[field]_[key] localisation format.
3
God icon path, from the working data folder.
Returns:
nil
-
cm:notify_god_total_favour_changed(faction keystring,god keystring,favournumber) -
Notifies the game that the total favour for a particular god has changed.
Parameters:
1
Faction key, from the
factionsdatabase table.2
God key.
3
Total favour.
Returns:
nil
-
cm:notify_sea_peoples_invasion_army(military force cqi
number,target type
string,target key
string,target faction key
string,target pos x
number,target pos y
number
) -
Notifies the game that a Sea Peoples invasion army has appeared.
Parameters:
1
military force cqi
2
target type
3
target key
4
target faction key
5
target pos x
6
target pos y
Returns:
nil
-
cm:add_blood_river(idstring,tooltip keystring,xnumber,ynumber) -
Adds a blood river to the campaign map, or updates an existing one if there is already a blood river with the given id.
Parameters:
1
Unique river id.
2
Tooltip key, in the full [table]_[field]_[key] localisation format.
3
Logical position x.
4
Logical position y.
Returns:
nil
-
cm:clear_campaign_blood_rivers() -
Clears all blood rivers on the campaign map.
Returns:
nil
-
cm:set_info_additional_ers_effect_bundle(custom effect bundlecustom_effect_bundle) -
Supplies an additional ERS effect bundle. This is for situational use as a part of the scripted ERS system.
Parameters:
1
custom effect bundle
Returns:
nil
-
cm:set_info_additional_agent_action_effect_bundle(custom effect bundlecustom_effect_bundle) -
Supplies an additional agent action efect bundle. This is for situational use a part of a scripted agent action system.
Parameters:
1
custom effect bundle
Returns:
nil
-
cm:add_custom_battlefield(id
string,x
number,y
number,radius
number,dump campaign
boolean,loading screen override
string,script override
string,whole battle override
string,human alliance
number,launch immediately
boolean,is land battle
boolean,force autoresolve result
boolean,force land battle during siege
boolean,disable fortification towers (for siege battles)
boolean
) -
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
Id for this custom battle record. This may be used to later remove this override with
cm:remove_custom_battlefield.2
X logical co-ordinate of anchor position.
3
Y logical co-ordinate of anchor position.
4
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
If set to
true, the battle makes no attempt to load back into this campaign after completion.6
Key of a custom loading screen to use, from the
custom_loading_screenstable. 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
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
Path to an battle xml file which overrides the whole battle.
9
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
Launch the battle immediately without saving the campaign first.
11
Sets whether the following battle is a land battle. This is only required if when launching the battle immediately.
12
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.13
If set to
true, this will force a siege battle to be fought outside the settlement as a land battle14
If set to
true, fortification towers will not shootReturns:
nil
-
cm:remove_custom_battlefield(idstring) -
Removes a custom battle override previously set with
cm:add_custom_battlefield.Parameters:
1
id
Returns:
nil
-
cm:win_next_autoresolve_battle(faction keystring) -
The specified faction will win the next autoresolve battle.
Parameters:
1
Faction key, from the
factionstable.Returns:
nil
-
cm:modify_next_autoresolve_battle(attacker win chance
number,defender win chance
number,attacker losses modifier
number,defender losses modifier
number,kill loser
boolean
) -
Modifies the result of the next autoresolved battle.
Parameters:
1
Attacker win chance as a unary (0-1) value.
2
Defender win chance as a unary (0-1) value.
3
Multiplier for losses sustained by the attacker.
4
Multiplier for losses sustained by the defender.
5
Forces the loser of the battle to be wiped out if set to
true.Returns:
nil
-
cm:override_attacker_win_chance_prediction(chancenumber) -
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
Chance as a percentage, so a value of
50would display a 50/50 attacker/defender balance.Returns:
nil
-
cm:skip_winds_of_magic_gambler(should skipboolean) -
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
should skip
Returns:
nil
-
cm:force_night_battle(enablestring) -
Forces the currently pending battle to be a night battle even if the general does not have the skill.
Parameters:
1
will force the battle to be a night battle if this is true
Returns:
nil
-
cm:force_pending_battle_complete() -
Forces the pending battle to complete, closing the pre-battle screen. This is intended for use pre-battle and might not work reliably if used at other times.
Returns:
nil
-
cm:set_dynamic_weather_force_disabled(disableboolean) -
Enables or disables dynamic weather in the forthcoming battle.
Parameters:
1
disable
Returns:
nil
-
cm:pending_battle_select_divine_ability(ability keystring,faction keystring) -
Sets the selected divine ability for the specified faction in the pending battle.
Parameters:
1
Army special ability key, from the
army_special_abilitiesdatabase table.2
Faction key, from the
factionsdatabase table.Returns:
nil
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:
| 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(faction keystring,personality keystring) -
Force the specified faction to adopt the specified AI personality.
Parameters:
1
Faction key, from the
factionstable.2
Personality key, from the
cai_personalitiestable.Returns:
nil
-
cm:set_campaign_ai_force_all_factions_bordering_humans_to_have_invasion_behaviour(force behaviour
boolean
) -
Force minor (non-rebel) factions to have the region group expansion behaviour if they border player-owned territory.
Parameters:
1
force behaviour
Returns:
nil
-
cm:set_campaign_ai_force_all_factions_bordering_human_vassals_or_subjects_to_have_invasion_behaviour(force behaviour
boolean
) -
Force minor (non-rebel) factions to have the region group expansion behaviour if they border player-protected factions.
Parameters:
1
force behaviour
Returns:
nil
-
cm:cai_strategic_stance_manager_block_all_stances_but_that_specified_towards_target_faction(faction key
string,target faction key
string,strategic stance key
string
) -
Sets one faction's stance towards another to the supplied strategic stance.
Parameters:
1
Faction key, from the
factionstable.2
Target faction key, from the
factionstable.3
Strategic stance key - see the list at the top of this section.
Returns:
nil
-
cm:cai_strategic_stance_manager_promote_specified_stance_towards_target_faction(faction key
string,target faction key
string,strategic stance key
string
) -
Makes it much more likely that one faction's stance towards another will be the supplied strategic stance.
Parameters:
1
Faction key, from the
factionstable.2
Target faction key, from the
factionstable.3
Strategic stance key - see the list at the top of this section.
Returns:
nil
-
cm:cai_force_personality_change(faction keystring) -
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
Faction key, from the
factionstable, or "all".Returns:
nil
-
cm:cai_force_personality_change_with_override_round_number(faction keystring,round numbernumber) -
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
Faction key, from the
factionstable, or "all".2
Override for turn/round number.
Returns:
nil
-
cm:cai_strategic_stance_manager_force_stance_update_between_factions(faction key
string,target faction key
string
) -
Forces a stance update from one faction to another faction. The AI picks an appropriate new strategic stance.
Parameters:
1
Faction key, from the
factionstable.2
Target faction key, from the
factionstable.Returns:
nil
-
cm:cai_strategic_stance_manager_set_stance_promotion_between_factions_for_a_given_stance(faction key
string,target faction key
string,strategic stance key
string,start round
number,start level
number,end round
number,end level
number
) -
Sets up a process which promotes a particular strategic stance from one faction to a target faction over a number of turns.
Parameters:
1
Faction key, from the
factionstable.2
Target faction key, from the
factionstable.3
Strategic stance key - see the list at the top of this section.
4
Starting round number.
5
Starting stance level. This is a numerical indicator of how likely this stance is to be chosen.
6
End round number.
7
End stance level. This is a numerical indicator of how likely this stance is to be chosen.
Returns:
nil
-
cm:cai_strategic_stance_manager_clear_all_promotions_between_factions(faction key
string,target faction key
string
) -
Clears any existing scripted stance promotions from one faction to a target faction.
Parameters:
1
Faction key, from the
factionstable.2
Target faction key, from the
factionstable.Returns:
nil
-
cm:cai_strategic_stance_manager_set_stance_blocking_between_factions_for_a_given_stance(faction key
string,target faction key
string,strategic stance key
string,round number
number
) -
Blocks a specific strategic stance from one faction to another faction until a specified round number.
Parameters:
1
Faction key, from the
factionstable.2
Target faction key, from the
factionstable.3
Strategic stance key - see the list at the top of this section.
4
Final round number (inclusive) of blocking behaviour.
Returns:
nil
-
cm:cai_strategic_stance_manager_clear_all_blocking_between_factions(faction key
string,target faction key
string
) -
Clears any existing scripted stance promotions between one faction and a target.
Parameters:
1
Faction key, from the
factionstable.2
Target faction key, from the
factionstable.Returns:
nil
-
cm:cai_disable_movement_for_character(character lookupstring) -
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
Character lookup string - see
Character Lookupsfor more information.Returns:
nil
-
cm:cai_enable_movement_for_character(character lookupstring) -
Allows the AI to move a character again after it was previously blocked with
cm:cai_disable_movement_for_character.Parameters:
1
Character lookup string - see
Character Lookupsfor more information.Returns:
nil
-
cm:cai_disable_movement_for_faction(faction keystring) -
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
Faction key, from the
factionstable.Returns:
nil
-
cm:cai_enable_movement_for_faction(faction keystring) -
Allows the AI to move characters in a faction again after it was previously blocked with
cm:cai_disable_movement_for_faction.Parameters:
1
Faction key, from the
factionstable.Returns:
nil
-
cm:cai_disable_command_assignment_for_character(character lookupstring) -
Prevents the AI from assigning the specified character to a position of command.
Parameters:
1
Character lookup string - see
Character Lookupsfor more information.Returns:
nil
-
cm:cai_enable_command_assignment_for_character(character lookupstring) -
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
Character lookup string - see
Character Lookupsfor more information.Returns:
nil
-
cm:cai_add_region_hint(factionfaction,region keystring) -
Adds a region to the VICTORY_CONDITION hint list of the faction.
Parameters:
1
Faction for which the hint will be added.
2
Region key for region to be added.
Returns:
nil
-
cm:cai_remove_region_hint(factionfaction,region keystring) -
Removes a region from the VICTORY_CONDITION hint list of the faction, after it has previously been added via
cm:cai_add_region_hint.Parameters:
1
Faction for which the hint will be added.
2
Region key for region to be added.
Returns:
nil
-
cm:cai_disable_targeting_against_region_slot(region slot keystring) -
Disables AI targeting of a specified region slot.
Parameters:
1
region slot key
Returns:
nil
-
cm:cai_enable_targeting_against_region_slot(region slot keystring) -
Re-enables AI targeting of a specified region slot.
Parameters:
1
region slot key
Returns:
nil
-
cm:cai_disable_targeting_against_settlement(settlement keystring) -
Disables AI targeting of a specified settlement.
Parameters:
1
settlement key
Returns:
nil
-
cm:cai_enable_targeting_against_settlement(settlement keystring) -
Re-enables AI targeting of a specified settlement.
Parameters:
1
settlement key
Returns:
nil
Script context values may be set to compel changes in AI behaviour based on scripted events (e.g. a scripted invasion). AI personalities can be set up in the database to adopt different policies and alter their priorities in response to scripted context values. Context values may be set globally with cm:cai_set_global_script_context, or per-faction with cm:cai_set_faction_script_context.
The following strings are valid AI script context values:
"DEFAULT""ALPHA""BETA""GAMMA""DELTA""EPSILON""ZETA"
The meaning of these values and the changes they effect are entirely defined within the AI-related tables in the dabatase.
-
cm:cai_set_global_script_context(valuestring) -
Sets the global script context value.
Parameters:
1
Value to set. Valid values are
"DEFAULT","ALPHA","BETA","GAMMA","DELTA","EPSILON"and"ZETA".Returns:
nil
-
cm:cai_get_global_script_context() -
Returns the current global script context value.
Returns:
string
-
cm:cai_clear_global_script_context() -
Clears the current global script context value, setting it to
"DEFAULT".Returns:
nil
-
cm:cai_set_faction_script_context(faction keystring,valuestring) -
Sets the script context value for the specified faction.
Parameters:
1
Faction key, from the
factionsdatabase table.2
Value to set. Valid values are
"DEFAULT","ALPHA","BETA","GAMMA","DELTA","EPSILON"and"ZETA".Returns:
nil
-
cm:cai_get_faction_script_context(faction keystring) -
Returns the current script context value for the specified faction.
Parameters:
1
Faction key, from the
factionsdatabase table.Returns:
string
-
cm:cai_clear_faction_script_context(faction keystring) -
Clears the script context value for the specified faction, setting it to
"DEFAULT".Parameters:
1
Faction key, from the
factionsdatabase table.Returns:
nil
The functions in this section relate to manipulating audio.
-
cm:activate_music_trigger(eventstring) -
Triggers any valid Wwise event.
Parameters:
1
Wwise event key.
Returns:
nil
-
cm:trigger_sound_event(sound_eventstring) -
Triggers any valid sound event by key.
Parameters:
1
Sound event key.
Returns:
nil
-
cm:trigger_music_state(music_faction
string,valid_timer
number,instant_change
boolean,sound_event
[string]
) -
Triggers a change to music state.
Parameters:
1
Music faction key.
2
Float timer.
3
Instant change flag.
4
optional, default value=false
Optional sound event.
Returns:
nil
-
cm:update_sound_state(sound state group idstring,sound state idstring) -
Updates the sound state. Sound state id strings may be obtained from the audio team.
Parameters:
1
sound state group id
2
sound state id
Returns:
nil
-
cm:set_incident_ambience_sound(incident namestring,regionstable) -
Sets incident id and regions for the ambient sound trigger.
Parameters:
1
Incident name, from the
incidentsdatabase table.2
Indexed table of region keys, each from the
campaign_map_regionsdatabase table.Returns:
nil
-
cm:set_music_vm_bool(triggerstring,valueboolean) -
Sets a boolean setting within the music virtual machine. Available settings are available from the audio team.
Parameters:
1
trigger
2
value
Returns:
nil
The shared states system allows variables to be set and read by script, the campaign model and the UI. The variables in question must be agreed between all parties.
Shared state values may be read by script using the shared_states_manager interface, accessible from the model interface. Values may be written to using the functions below.
The script event SharedStateChanged is triggered whenever a shared states value is changed.
-
cm:set_script_state([objectobject],keystring, valuevalue) -
Sets the value of a shared state. An optional object with which the value is associated, such as a faction script interface, may be supplied as the first argument.
Parameters:
1
objectoptional, default value=nil
Interface object to associate the shared value with. This argument may be omitted.
2
Key of shared value to set.
3
valueValue to set. Supported value types are
boolean,numberandstring.Returns:
nil
Example - Setting shared value "faction_progress_counter" related to a faction:
cm:set_script_state(cm:get_faction("wh_main_emp_empire"), "faction_progress_counter", 5)
Example - Setting global shared value:
cm:set_script_state("all_factions_progress_counter", 15)
-
cm:remove_script_state([objectobject],keystring) -
Removes a value from the shared state system. An optional object with which the value is associated, such as a faction script interface, may be supplied as the first argument.
Parameters:
1
objectoptional, default value=nil
Interface object to associate the shared value with. This argument may be omitted.
2
Key of shared value to set.
Returns:
nil
-
cm:get_bool_script_state([objectobject],keystring) -
Gets the value of a boolean shared state. An optional object with which the value is associated, such as a faction script interface, may be supplied as the first argument.
Parameters:
1
objectoptional, default value=nil
Interface object to associate the shared value with. This argument may be omitted.
2
Key of shared value to get.
Returns:
boolean
Example - Getting shared value "is_something" related to a faction:
local is_something = cm:get_bool_script_state(cm:get_faction("wh_main_emp_empire"), "is_something")
Example - Setting global shared value:
local end_game_event_has_started = cm:get_bool_script_state("end_game_event_has_started")
-
cm:get_float_script_state([objectobject],keystring) -
Gets the value of a float shared state. An optional object with which the value is associated, such as a faction script interface, may be supplied as the first argument.
Parameters:
1
objectoptional, default value=nil
Interface object to associate the shared value with. This argument may be omitted.
2
Key of shared value to get.
Returns:
number
Example - Getting shared value "num_special_faction_mechanic_points" related to a faction:
local num_special_faction_mechanic_points = cm:get_float_script_state(cm:get_faction("wh_main_emp_empire"), "num_special_faction_mechanic_points")
Example - Setting global shared value:
local num_factions_unlocked_specific_mechanic = cm:get_float_script_state("num_factions_unlocked_specific_mechanic")
-
cm:get_string_script_state([objectobject],keystring) -
Gets the value of a string shared state. An optional object with which the value is associated, such as a faction script interface, may be supplied as the first argument.
Parameters:
1
objectoptional, default value=nil
Interface object to associate the shared value with. This argument may be omitted.
2
Key of shared value to get.
Returns:
string
Example - Getting shared value "favorite_lord_key" related to a faction:
local favorite_lord_key = cm:get_string_script_state(cm:get_faction("wh_main_emp_empire"), "favorite_lord_key")
Example - Setting global shared value:
local world_leader_key = cm:get_string_script_state("world_leader_key")
-
cm:create_new_custom_resource_cost() -
Creates and returns a
custom_resource_costobject. This object can then be customised by calling functions on the interface it provides, and then used for various purposes.Returns:
custom_resource_cost
-
cm:create_custom_unit_from_key() -
Creates and returns a
custom_unitobject. The unit can then be customised by calling functions on the interface it provides.Returns:
custom_unit
-
cm:unlock_achievement(faction keystring,achievement keystring) -
Unlocks an achievement for a faction.
Parameters:
1
Faction key, from the
factionsdatabase table.2
from the
achievementsdatabase table.Returns:
nil