Episodic Scripting
The episodic scripting interface is one of the two main interface provided by the campaign model to script. Unlike the model_hierarchy interfaces, which are generally used to query the state of the model, the episodic scripting interface is primarily used to make changes to the model.
| Loaded in Campaign |
|
| Loaded in 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. |
family_member_cqi | The command queue index of the character's family member interface. This is always unique. |
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 Empire faction at a display position [123,456]:
cm:force_add_trait("faction:wh_main_emp_empire,x:123,y:456,r:1", "trait_general_good", true)
Example - Remove all action points from a character with cqi 45:
cm:zero_action_points("character_cqi:45")
Example - Use the char_lookup_str function to disable movement for the faction leader of the Greenskins:
local char_grn_faction_leader = cm:get_faction("wh_main_grn_greenskins"):faction_leader()
cm:disable_movement_for_character(cm:char_lookup_str(char_grn_faction_leader))
-
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:is_replay() -
Returns whether this a campaign replay.
Returns:
boolean
-
cm:is_cinematic_editor_attached() -
Returns whether the cinematic editor tool is currently attached to the game.
Returns:
boolean
-
cm:model() -
Returns a handle to the campaign model object.
Returns:
model
-
cm:filesystem_lookup(pathstring) -
Perform a VFS lookup in the specified path (root is the data folder) for files matching the pattern. Returns a comma-delimited list of files found.
Parameters:
1
path
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:is_dlc_flag_enabled(dlc product keystring,player faction keystring) -
Returns whether the dlc with the specified key is activated for the given player, specified by faction.
Parameters:
1
dlc product key
2
player faction key
Returns:
dlcflag enabled for this faction
-
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: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: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:trigger_campaign_vo(sound eventstring,character lookupstring,delaynumber) -
Triggers campaign voiceover audio at a character's 3D position. The character specified also partially specifies the path by which the voiceover sound is looked up.
Parameters:
1
Sound event name.
2
Character lookup string - see
Character Lookupsfor more information.3
Delay in seconds before triggering the vo.
Returns:
nil
-
cm:stop_campaign_vo(sound eventstring) -
Stops a playing campaign voiceover sound event.
Parameters:
1
Sound event name.
Returns:
nil
-
cm:stop_campaign_advisor_vo() -
Stops any playing campaign advisor voiceover.
Returns:
nil
-
cm:trigger_2d_ui_sound(sound eventstring,delaynumber) -
Triggers a sound event in 2D, so that it appears to play behind the camera.
Parameters:
1
Sound event name.
2
Delay before playing the sound, in ms.
Returns:
nil
-
cm:stop_2d_ui_sound(sound eventstring) -
Stops a playing 2D sound event by name.
Parameters:
1
Sound event name.
Returns:
nil
-
cm:activate_music_trigger(trigger namestring,trigger argumentstring) -
Activates a trigger within the music system. A string argument must also be supplied.
Parameters:
1
trigger name
2
trigger argument
Returns:
nil
-
cm:set_music_paused(pauseboolean) -
Pauses or unpauses any playing music.
Parameters:
1
Pause the music. If
falseis specified then the music is unpaused.Returns:
nil
-
cm:set_global_vo_argument(state groupstring,statestring) -
Sets a VO state that can be used to alter what VO will play.
Parameters:
1
state group
2
state
Returns:
nil
-
cm:contextual_vo_enabled(enable contextual voboolean) -
Enables or disables contextual VO sounds. By default contextual vo is enabled - use this function to disable it.
Parameters:
1
enable contextual vo
Returns:
nil
-
cm:add_character_actor_group_override(charactercharacter,actor vo record keystring) -
Override the actor of the desired character with an actor id from the provided actor group record.
Parameters:
1
characterCharacter interface.
2
Actor VO record key, from the
audio_vo_actorsdatabase table.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: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.
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:enable_camera_bearing_clamp(min rotationnumber,max rotationnumber) -
Enables a yaw (side to side) rotation constraint on the camera. Such a constraint may be later unset with
cm:disable_camera_bearing_clamp.Parameters:
1
Minimum rotation value in radians. A value less than zero is permissable.
2
Maximum rotation value in radians.
Returns:
nil
-
cm:disable_camera_bearing_clamp(min rotationnumber,max rotationnumber) -
Disables a yaw rotation clamp previously enabled with
cm:enable_camera_bearing_clamp.Parameters:
1
Minimum rotation value in radians. A value less than zero is permissable.
2
Maximum rotation value in radians.
Returns:
nil
-
cm:set_camera_height(heightnumber) -
Immediately sets the camera height.
Parameters:
1
height
Returns:
nil
-
cm:set_camera_minimum_height(heightnumber) -
Sets a minimum height for the camera.
Parameters:
1
height
Returns:
nil
-
cm:set_camera_maximum_height(heightnumber) -
Sets a minimum height for the camera.
Parameters:
1
height
Returns:
nil
-
cm:register_instant_movie(movie pathstring) -
Plays a fullscreen movie, by path from the
data/Moviesdirectory.Parameters:
1
movie path
Returns:
nil
Example:
-- play the movie file data/Movies/Warhammer/chs_rises
cm:register_instant_movie("Warhammer/chs_rises")
-
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:end_turn([forceboolean]) -
Ends the turn for the current faction, optionally forcing at the next opportunity. This optional flag should only be set for a player faction.
Parameters:
1
optional, default value=false
force
Returns:
nil
-
cm:end_turn_for_faction(factionfaction) -
Ends the turn for the specified faction.
Parameters:
1
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:disable_end_turn(should disableboolean) -
Disables or re-enables the local player's ability to end the turn.
Parameters:
1
should disable
Returns:
nil
-
cm:set_skip_faction_turn(factionfaction,should skipboolean) -
Set a faction to have their turn skipped, or not. A faction that is skipped is entirely removed from the turn sequence, no start/end of turn/round will be ran on them or objects they own.
Parameters:
1
faction
2
should skip
Returns:
nil
-
cm:skip_all_ai_factions() -
Set all AI factions to have their turn skipped. A faction that is skipped is entirely removed from the turn sequence, no start/end of turn/round will be ran on them or objects they own.
Returns:
nil
-
cm:unskip_all_factions() -
Restore the turn of every faction in the game, undoing any skipping behaviour previously set with
cm:set_skip_faction_turnorcm:skip_all_ai_factions.Returns:
nil
-
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 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: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, from the
campaign_character_art_setsdatabase table.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:toggle_character_hidden_from_view(charactercharacter,hideboolean) -
Hides or unhides a character from the view.
Parameters:
1
character
2
hide
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:set_army_outer_movement_extents_rendering_disabled(should disableboolean) -
Globally disable or enable army movement extents from rendering.
Parameters:
1
should disable
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: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 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: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 cqinumber,vfxstring,show in shroudboolean) -
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.
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 cqinumber,vfxstring,show in shroudboolean) -
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.
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,faction
[faction]
) -
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.
10
optional, default value=nil
Faction this composite scene is visible to. Defaults to all factions if not set.
Returns:
boolean
-
cm:add_scripted_composite_scene_to_settlement(name
string,composite scene
string,region
region,facing x
number,facing y
number,one shot
boolean,show in seen shroud
boolean,show in unseen shroud
boolean,faction
[faction]
) -
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
region of the settlement to add the scene to
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.
9
optional, default value=nil
Faction this composite scene is visible to. Defaults to all factions if not set.
Returns:
boolean
-
cm:add_scripted_composite_scene_to_settlement_port(name
string,composite scene
string,Region
region,facing x
number,facing y
number,one shot
boolean,show in seen shroud
boolean,show in unseen shroud
boolean,faction
[faction]
) -
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
Region of the settlement to add the scene to
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.
9
optional, default value=nil
Faction this composite scene is visible to. Defaults to all factions if not set.
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
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:reset_shroud([factionfaction]) -
Resets the shroud of a specified faction. If no faction is specified, the shrouds of all factions are reset.
Parameters:
1
optional, default value=nil
faction
Returns:
nil
-
cm:take_shroud_snapshot() -
Caches the state of the shroud across the map, so that it may later be recalled with
cm:restore_shroud_from_snapshot.Returns:
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: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: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:force_terrain_patch_visible(patchstring) -
Forces a terrain patch to be visible, alongside its associated props, trees and areas of interest. If an empty string is passed then all patch areas will be visible. The visibility change applies to all factions.
Parameters:
1
Terrain patch key, from the
campaign_terrain_patch_areasdatabase table.Returns:
nil
-
cm:reset_forced_terrain_patch_visibility() -
Resets all terrain patch visility changes previously made with
cm:force_terrain_patch_visible.Returns:
nil
-
cm:grant_faction_additional_vision(factionfaction,region dataregion_data, [durationnumber]) -
Grants a faction visibility over a region they might not otherwise be able to see for a number of turns, or indefinitely. This additional vision will persist through shroud recalculations.
Parameters:
1
Faction interface.
2
Region data interface.
3
optional, default value=0
Duration of the additional visibility in turns. If a duration of 0 or less is supplied, or if this argument is omitted, then the vision will be granted indefinitely.
Returns:
nil
-
cm:remove_faction_additional_vision(factionfaction,region dataregion_data) -
Removes a faction's additional visibility over a region. If no additional visiblity was set for this faction/region with
cm:grant_faction_additional_visionthen nothing will happen.Parameters:
1
Faction interface.
2
Region data interface.
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: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.
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.
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.
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_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.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_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_agent_at_position(factionfaction,xnumber,ynumber,agent typestring, [agent subtypestring]) -
Spawns an agent of the specified type at the specified logical position.
Parameters:
1
Faction interface for the agent's faction.
2
x logical co-ordinate.
3
y logical co-ordinate.
4
Agent type key, from the
agentstable.5
optional, default value=""
Agent subtype key, from the
agent_subtypestable. This can be omitted.Returns:
nil
-
cm:spawn_agent_at_settlement(faction
faction,settlement
settlement,agent type
string,agent subtype
[string]
) -
Spawns an agent of the specified type next to the specified settlement.
Parameters:
1
Faction interface for the agent's faction.
2
Settlement at which to spawn the agent.
3
Agent type key, from the
agentstable.4
optional, default value=""
Agent subtype key, from the
agent_subtypestable. This can be omitted.Returns:
nil
-
cm:spawn_agent_at_military_force(faction
faction,force
military_force,agent type
string,agent subtype
[string]
) -
Spawns an agent of the specified type next to the specified military force.
Parameters:
1
Faction interface for the agent's faction.
2
Military force at which to spawn the agent.
3
Agent type key, from the
agentstable.4
optional, default value=""
Agent subtype key, from the
agent_subtypestable. This can be omitted.Returns:
nil
-
cm:embed_agent_in_force(agentcharacter,military forcemilitary_force) -
Instantly embed the specified agent in the specified force. The agent will teleport into the force, disregarding normal restrictions other than that force being under siege.
Parameters:
1
agent
2
military force
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_rogue_army(xnumber,ynumber) -
Spawns a rogue army of a specified rogue army faction, at a specified position. This command will fail if the rogue army is already alive or is flagged to naturally spawn.
stringfaction key, Faction key, from thefactionsdatabase table.Parameters:
1
Logical x co-ordinate.
2
Logical y co-ordinate.
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. The
character_detailsinterface related to the spawned character is returned.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:
character_details
-
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: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_character_recruitment(startpos idstring,faction keystring) -
Locks recruitment of a starting character, 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_character_recruitment(startpos idstring,faction keystring) -
Unlocks recruitment of a starting character, 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:replace_general_in_force(military forcemilitary_force,agent subtypestring) -
Replaces the commanding general of the specified military force with a new character of the specified agent subtype. The new commanding character is returned.
Parameters:
1
Military force interface.
2
Agent subtype key, from the
agent_subtypesdatabase table.Returns:
character
-
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 specified character, through a family member interface.
Parameters:
1
family memmber interface.
2
Experience points to award.
Returns:
nil
-
cm:add_experience_to_unit(unitunit,experience level to addnumber) -
Adds experience points to a supplied unit's existing experience level.
Parameters:
1
unit
2
experience level to add
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: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:set_unit_experience_disabled(disableboolean) -
Disables or re-enables units 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,unit keystring) -
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
Key of unit to create, from the
main_unitstable.Returns:
nil
-
cm:move_to(character lookupstring,xnumber,ynumber) -
Orders the specified character to move to a specified logical position. This is equivalent to the player or AI issuing the same order, and as such should only be done on that faction's turn.
Note that if the character is in a settlement, or the intended destination is a settlement, an enemy army, or another kind of special obstacle then it's likely that a different type of order is required - seecm:join_garrison,cm:leave_garrisonandcm:attack, for example.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:move_to_queued(character lookupstring,xnumber,ynumber) -
Orders the specified character to move to a specified logical position. This action is queue if another action is currently active.
Note that if the character is in a settlement, or the intended destination is a settlement, an enemy army, or another kind of special obstacle then it's likely that a different type of order is required - seecm:join_garrison,cm:leave_garrisonandcm:attack, for example.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:teleport_to(character lookupstring,xnumber,ynumber) -
Orders the specified character to immediately teleport to a specified logical position. This order should only be given on that faction's turn.
Parameters:
1
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_military_force_to(military forcemilitary_force,xnumber,ynumber) -
Immediately teleports the supplied military force to a specified logical position. This order should only be given on that faction's turn.
Parameters:
1
Military force.
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 is equivalent to the player or AI issuing the same order, and as such should only be done on that faction's turn.
Parameters:
1
Character lookup string. For more information, see
Character Lookups.2
Key of settlement containing the garrison residence, from the
campaign_map_settlementstable.Returns:
nil
-
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:attack(character lookup
string,target character lookup
string,lay siege
[boolean],ignore shroud
[boolean]
) -
Orders the specified character to attack a target character. This is equivalent to the player or AI issuing the same order, and as such should only be done on that faction's turn.
Parameters:
1
Character lookup string. For more information, see
Character Lookups.2
Target character lookup string. For more information, see
Character Lookups.3
optional, default value=false
Lay siege if the target is a garrison residence.
4
optional, default value=true
Ignores shroud restrictions. If this is set to
falsethen the attack command is ignore if the attacker cannot see the target.Returns:
nil
-
cm:attack_region(character lookupstring,region keystring) -
Orders the specified character to initiate an attack on the settlement in a target region. If the character cannot initiate a battle (for example he or she currently has no method to defeat the fortifications) then nothing will happen.
Parameters:
1
Character lookup string. For more information, see
Character Lookups.2
Region key containing the target settlement, from the
campaign_map_regionstable.Returns:
nil
-
cm:attack_queued(target character lookupstring, [lay siegeboolean]) -
Orders the specified character to attack a target character. This command is added to a queue if another queued attacker is currently active.
Parameters:
1
Target character lookup string. For more information, see
Character Lookups.2
optional, default value=false
Lay siege if the target is a garrison residence.
Returns:
nil
-
cm:force_attack_of_opportunity(attacker cqinumber,target cqinumber,is ambushboolean) -
Orders the specified character to attack a target character through an attack of opportunity - either an interception or an ambush. Note that this function requires character cqis to be passed in as arguments and not lookup strings.
The two characters must be of different factions that are at war and neither may be garrisoned for the action to succeed.Parameters:
1
Command-queue index of the attacking character.
2
Command-queue index of the target character.
3
Set to
trueto ambush, orfalseto intercept.Returns:
nil
-
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.
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:
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: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: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: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:stop_character_convalescing(character cqinumber) -
Instantly returns a convalescing (wounded) character to the available pool of recruitable characters for their faction.
Parameters:
1
character cqi
Returns:
nil
-
cm:modify_character_personal_loyalty_factor(character lookupstring,loyalty modifiernumber) -
Modifies the loyalty of a specified character.
Parameters:
1
Character lookup string. For more information, see
Character Lookups.2
Amount to modify the loyalty by. This may be positive or negative.
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:convert_force_to_type(forcemilitary_force,typestring) -
Converts a military force to a specific type.
Parameters:
1
Military force.
2
Military force type, from the
military_force_typestable.Returns:
nil
-
cm:heal_military_force(forcemilitary_force) -
Heals the supplied military force back to full health.
Parameters:
1
Military force.
Returns:
nil
-
cm:set_unit_hp_to_unary_of_maximum(unitunit,unary hpnumber) -
Sets the hit points/number of men to the given unary proportion of the maximum for that unit.
Parameters:
1
Unit.
2
Unary proportion (0-1) of max hp value to set unit health to.
Returns:
nil
-
cm:set_army_trespass_disabled(should disableboolean) -
Globally disable or enable army trespassing penalties.
Parameters:
1
should disable
Returns:
nil
-
cm:set_multi_turn_movement_enabled(should enableboolean) -
Globally enable or disable multiturn movement. If disabled, characters will only be able to walk to the extents allowed by their remaining action points.
Parameters:
1
should enable
Returns:
nil
-
cm:set_character_path_traversal_speed_multiplier(charactercharacter,multipliernumber) -
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_character_excluded_from_trespassing(charactercharacter,excludedboolean) -
Sets a character to be excluded from trespassing calculations or not.
Parameters:
1
Character interface.
2
Should the character be excluded.
Returns:
nil
-
cm:set_force_has_retreated_this_turn(military forcemilitary_force) -
Sets a military force so that it behaves as if it's already retreated from battle this turn.
Parameters:
1
military force
Returns:
nil
-
cm:set_character_cannot_disband(charactercharacter,stop disbandingboolean) -
Sets whether the provided character can disband or not.
Parameters:
1
Character interface.
2
Stop the desired character from disbanding.
Returns:
nil
-
cm:suppress_immortality(fm cqinumber,suppressboolean) -
Suppresses or un-suppresses the immortality of the specified character. The character is specified by the command-queue index value of the related
family_memberinterface.Parameters:
1
Family member cqi.
2
Suppress immortality.
Returns:
nil
Certain characters may be equipped with armory items. These items are listed in the armory_items database table.
-
cm:add_armory_item_to_character(character
character,armory item
string,equip default
boolean,clear conflicting items
boolean
) -
Adds an armory item to a character.
Parameters:
1
Character to add item to.
2
Key for armory item to equip, from the
armory_itemsdatabase table.3
Equips a default variant of the armory item (if one exists) if the target slot on the character is empty. Armory item variants are defined in the
armory_item_variantsdatabase table.4
Unequips any conflicting items when this item is equipped.
Returns:
boolean
-
cm:remove_armory_item_from_character(charactercharacter,armory itemstring) -
Removes an armory item from a character.
Parameters:
1
Character to remove item from.
2
Key for armory item to unequip, from the
armory_itemsdatabase table.Returns:
boolean
-
cm:unequip_all_armory_items_from_character(charactercharacter) -
Unequips all armory items equipped by the specified character.
Parameters:
1
Character to remove items from.
Returns:
boolean
-
cm:equip_armory_item_variant_on_character(character
character,item variant
string,clear conflicting items
boolean
) -
Equips a specific variant of an armory item on the specified character.
Parameters:
1
Character to add item to.
2
Variant of armory item to equip, from the
armory_item_variantsdatabase table.3
Unequips any conflicting items when this item is equipped.
Returns:
boolean
-
cm:unequip_armory_item_variant_from_character(charactercharacter,item variantstring) -
Unequips a specific variant of an armory item from the specified character.
Parameters:
1
Character to add item to.
2
Variant of armory item to unequip, from the
armory_item_variantsdatabase table.Returns:
boolean
-
cm:unequip_active_item_variant_in_slot_from_character(charactercharacter,armory slotstring) -
Unequips any amory item variant from the specified slot of the specified character.
Parameters:
1
Character to add item to.
2
Armory slot key, from the
armory_slot_typesdatabase table.Returns:
nil
-
cm:add_armory_item_set_to_character(item set
string,equip default
boolean,clear conflicting items
boolean
) -
Adds all armory items in the specified armory set to the specified character.
Parameters:
1
Key for armory item set to equip, from the
armory_item_setsdatabase table.2
Equips a default variant of each armory item (if one exists) if the target slot on the character is empty. Armory item variants are defined in the
armory_item_variantsdatabase table.3
Unequips any conflicting items when each item is equipped.
Returns:
boolean
-
cm:equip_armory_item_set_on_character(charactercharacter,armory item setstring) -
Equips all armory items in the specified armory set on the specified character.
Parameters:
1
Character to add item to.
2
Key for armory item set to equip, from the
armory_item_setsdatabase table.Returns:
boolean
-
cm:is_armory_item_compatible_with_categories_on_character(charactercharacter,armory itemstring) -
Returns whether the supplied armory item can be equipped by the specified character, based on the armory set categories associated with that character.
Parameters:
1
Character to check.
2
Key for armory item to check, from the
armory_itemsdatabase table.Returns:
boolean
-
cm:is_armory_item_compatible_with_agent_subtype(charactercharacter,armory itemstring) -
Returns whether the specified armory item is compatible with the specified character's agent subtype.
Parameters:
1
Character to check.
2
Key for armory item to check, from the
armory_itemsdatabase table.Returns:
boolean
-
cm:can_armory_item_be_equipped_on_character(charactercharacter,armory itemstring) -
Returns whether the specified character can equip the specified armory item.
Parameters:
1
Character to check.
2
Key for armory item to check, from the
armory_itemsdatabase table.Returns:
boolean
-
cm:add_armory_item_category_set_membership(charactercharacter,categorystring) -
Add an armory set category to the specified character, allowing them to equip armory set items from that category.
Parameters:
1
Subject character.
2
Category key, from the
armory_items_category_setsdatabase table.Returns:
boolean
-
cm:remove_armory_item_category_set_membership(charactercharacter,categorystring) -
Removes an armory set category from the specified character, meaning they will no longer be able to equip armory items from that category.
Parameters:
1
Subject character.
2
Category key, from the
armory_items_category_setsdatabase table.Returns:
nil
-
cm:clear_armory_item_category_membership(charactercharacter) -
Removes all armory set categories from the specified character.
Parameters:
1
Subject character.
Returns:
nil
-
cm:get_active_armory_item_variant_slot_state_for_character(charactercharacter,item variantstring) -
Returns the active slot state for the specified armory item variant on the specified character. If no slot state value can be found then
"INVALID"is returned.Parameters:
1
Character to add item to.
2
Variant of armory item to query, from the
armory_item_variantsdatabase table.Returns:
string
Character tinting is used in certain circumstances to colourise a character and indicate certain information about that character to the player, such as the current allegiance of a Daemon Prince.
-
cm:set_tint_activity_state_for_character(charactercharacter,enable tintingboolean) -
Enables or disables tinting on the supplied character.
Parameters:
1
character
2
enable tinting
Returns:
nil
-
cm:get_tint_activity_state_for_character(charactercharacter) -
Returns whether tinting is active on the supplied character.
Parameters:
1
character
Returns:
boolean
-
cm:set_tint_colour_for_character(character
character,first colour key
string,first colour intensity
number,second colour key
string,second colour intensity
number
) -
Sets the tint colour for the specified character. Two colour keys from the
coloursdatabase table are specified, and an intensity value for each.Parameters:
1
character interface.
2
First colour key, from the
coloursdatabase table.3
Intensity of the first colour. This should be a number in the range
0-255.4
Second colour key, from the
coloursdatabase table.5
Intensity of the second colour. This should be a number in the range
0-255.Returns:
nil
-
cm:toggle_initiative_active(INITIATIVE_INTERFACEinitiative,set activeboolean) -
Sets an initiative to active/inactive. A
booleanvalue indicating whether the toggle was successful is returned.Parameters:
1
INITIATIVE_INTERFACEinitiative
2
set active
Returns:
boolean
-
cm:toggle_initiative_script_locked(INITIATIVE_INTERFACEinitiative,script lockedboolean) -
Sets whether an initiative is script locked. A
booleanvalue indicating whether the toggle was successful is returned.Parameters:
1
INITIATIVE_INTERFACEinitiative
2
script locked
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_traitsdatabase table.3
optional, default value=1
Number of trait points to add.
Returns:
nil
-
cm:force_add_trait_to_character_details(character detailscharacter_details,trait keystring) -
Grant the specified trait to the specified character, using the character's persistent character details interface. If the character already has the trait, a trait point will be added.
Parameters:
1
Character details interface related to the subject character.
2
Trait key, from the
character_traitsdatabase table.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_traitsdatabase table.Returns:
nil
-
cm:force_add_ancillary(target_character
character,ancillary key
string,force equip
boolean,suppress event feed
boolean
) -
Grant the specified ancillary to the specified character.
Parameters:
1
target_character
2
Ancillary key, from the
ancillariestable.3
if true the ancillary will be equipped and bypass any cooldowns or pre-conditions
4
if true no event feed events will be generated by this action
Returns:
nil
-
cm:force_remove_ancillary(target_character
character,ancillary key
string,remove to pool
boolean,suppress event feed
boolean
) -
Remove the specified ancilliary from the specified character.
Parameters:
1
target_character
2
Ancillary key, from the
ancillariestable.3
Removes the ancillary from the character but leaves it in the pool of available ancillaries.
4
if true no event feed events will be generated by this action
Returns:
nil
-
cm:add_ancillary_to_faction(target factionfaction,ancillary keystring,suppress event feedboolean) -
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
target faction
2
Ancillary key, from the
ancillariestable.3
if true no event feed events will be generated by this action
Returns:
nil
-
cm:force_remove_ancillary_from_faction(factionfaction,ancillary keystring) -
Remove all instances of the specified ancillary from every character, and the shared ancillary pool, of the specified faction.
Parameters:
1
faction
2
Ancillary key, from the
ancillariestable.Returns:
nil
-
cm:reassign_ancillaries_to_character_of_same_faction(source character
character,destination character
character
) -
Reassign all ancillaries from one character to another.
Parameters:
1
source character
2
destination character
Returns:
nil
-
cm: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:remove_skill_point(character lookupstring,skill keystring) -
Remove a skill point from the specified character and skill. Returns
trueif successful.Parameters:
1
Character lookup string. For more information, see
Character Lookups.2
Skill key, from the
character_skillstable.Returns:
boolean
-
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:remove_all_background_skills(character lookupstring) -
Forcibly remove all background skills for the specified character.
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_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
cm:add_circle_area_triggerorcm:add_outline_area_triggerwith the supplied name.Parameters:
1
trigger name
Returns:
nil
-
cm:add_hex_area_trigger(trigger name
string,x
number,y
number,radius
number,faction key
[string],subculture key
[string]
) -
Establishes a area trigger monitor around a specified logical position, with a faction or subculture filter. This monitor will trigger an
AreaEnteredorAreaExitedscript event if a character that matches the filter moves through the area boundary.Parameters:
1
Unique name for this area trigger.
2
Logical x co-ordinate for the hex area.
3
Logical y co-ordinate for the hex area.
4
Radius in hexes (max of 20).
5
optional, default value=""
Key of faction to which the area trigger should apply, from the
factionstable. This may be a blank string if a subculture key is supplied.6
optional, default value=""
Key of subculture to which the area trigger should apply, from the
Returns:
nil
-
cm:remove_hex_area_trigger(trigger namestring) -
Removes any area triggers established with
cm:add_hex_area_triggerwith the supplied trigger name.Parameters:
1
trigger name
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 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 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 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 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 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 interface.
2
New name for the unit.
Returns:
nil
-
cm:change_character_custom_name(character
character,forename
string,surname
string,clan name
string,other name
string
) -
Replace the name of a character with a new value supplied directly from script. No database lookup will be performed. Be warned that our lua implementation only deals with ANSI strings, so the name will be limited to latin characters.
If a value is not required for a particular name type then a blank string may be supplied for that parameter.Parameters:
1
Target character.
2
Forename.
3
Surname.
4
Clan name.
5
Other name.
Returns:
nil
-
cm:change_character_localised_name(character
character,forename
string,surname
string,clan name
string,other name
string
) -
Replace the name of a character with a set of names from the database. Names must be specified by full localised text key, in the [table]_[key]_[field] format. Don't use this function on rebel characters.
If a value is not required for a particular name type then a blank string may be supplied for that parameter.Parameters:
1
Target character.
2
Localised forename key, in the [table]_[key]_[field] format.
3
Localised surname key, in the [table]_[key]_[field] format.
4
Localised clan name key, in the [table]_[key]_[field] format.
5
Localised other name key, in the [table]_[key]_[field] format.
Returns:
nil
Example:
local faction = cm:get_faction("wh3_main_ksl_the_ice_court");
cm:change_character_localised_name(faction, "names_name_1053468021", "names_name_1468066020", "", "");
-
cm:randomise_character_name(charactercharacter) -
Replace the name of the supplied character with a new random name from the pool. Don't use this function on rebel characters.
Parameters:
1
Target character.
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: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_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:add_development_points_to_horde(military forcemilitary_force,development pointsnumber) -
Add development points to a horde.
Parameters:
1
military force
2
Developments points to add.
Returns:
nil
-
cm:add_growth_points_to_region(region keystring,growth pointsnumber) -
Add growth points to a region
Parameters:
1
Region key, from the
campaign_map_regionstable.2
Growth points to add.
Returns:
nil
-
cm:add_growth_points_to_horde(military forcemilitary_force,growth pointsnumber) -
Add growth points to a horde.
Parameters:
1
military force
2
Growth 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: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:create_storm_for_region(region keystring,storm strengthnumber,durationnumber, [storm typestring]) -
Creates a storm of a given type in a given region.
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:heal_garrison(region cqinumber) -
Heals the garrison army (and navy, where applicable) in the specified region back to full health. The region is specified by cqi.
Parameters:
1
Command-queue index of the target region.
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:add_unit_to_faction_mercenary_pool(faction
faction,unit
string,recruitment source
string,count
number,replenishment chance
number,max units
number,max per turn
number,faction restriction
string,subculture restriction
string,tech restriction
string,partial replenishment
boolean,mercenary unit group
string
) -
Adds one or more units of a specified type to a faction's mercenary pool. These units can then be recruitable by that faction (or potentially other factions) using gameplay mechanics such as Regiments of Renown or Wulfhart's Mercenaries.
Parameters:
1
Faction whose pool the unit(s) should be added to.
2
Key of unit to add to the mercenary pool, from the
main_unitstable.3
Key of the recruitment pool that the unit will be available from, from the
recruitment_sourcestable.4
Number of units to add to the mercenary pool.
5
Replenishment chance, as a percentage. This is the chance per-turn that the number of available units in the pool of the supplied type will be increased, if not already at its maximum.
6
The maximum number of units of the supplied type that the pool is allowed to contain.
7
The maximum number of units of the supplied type that may be added by replenishment per-turn.
8
The key of the faction who can actually recruit the units, from the
factionsdatabase table. This may be different from the faction whose pool the unit is added to. An empty string""may be supplied to omit this, which will usually be the case.9
The key of the subculture who can actually recruit the units, from the
cultures_subculturesdatabase table. An empty string""may be supplied to omit this, which will usually be the case.10
The key of a technology that must be researched in order to recruit the units, from the
technologiesdatabase table.11
Allow replenishment of partial units.
12
The key of the mercenary unit group that contains the units you want to add, from the
mercenary_unit_groupsdatabase table.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. Unlike with
cm:add_units_to_faction_mercenary_pool, the unit type must already be represented in the pool.Parameters:
1
CQI of the subject faction.
2
Unit key, from the
main_unitstable.3
Number of units to add.
Returns:
nil
-
cm:add_unit_to_province_mercenary_pool(region
region,unit
string,count
number,replenishment chance
number,max units
number,max per turn
number,faction restriction
string,subculture restriction
string,tech restriction
string
) -
Adds one or more units of a specified type to the mercenary pool in a province. These units can then be recruitable by that faction (or potentially other factions) using gameplay mechanics such as Raising Dead.
Parameters:
1
Region within the province to which the unit(s) should be added.
2
Key of unit to add to the mercenary pool, from the
main_unitstable.3
Number of units to add to the mercenary pool.
4
Replenishment chance, as a percentage. This is the chance per-turn that the number of available units in the pool of the supplied type will be increased, if not already at its maximum.
5
The maximum number of units of the supplied type that the pool is allowed to contain.
6
The maximum number of units of the supplied type that may be added by replenishment per-turn.
7
The key of the faction who can actually recruit the units, from the
factionsdatabase table. This may be different from the faction whose pool the unit is added to. An empty string""may be supplied to omit this, which will usually be the case.8
The key of the subculture who can actually recruit the units, from the
cultures_subculturesdatabase table. An empty string""may be supplied to omit this, which will usually be the case.9
The key of a technology that must be researched in order to recruit the units, from the
technologiesdatabase table.Returns:
nil
-
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. Unlike with
cm:add_unit_to_province_mercenary_pool, the unit type must already be represented in the pool.Parameters:
1
Region key of a region within the target province, from the
campaign_map_regionstable.2
Unit key, from the
main_unitstable.3
Number of units to add.
Returns:
nil
-
cm:change_home_region_of_faction(factionfaction,regionregion) -
Updates the home region of a faction.
Parameters:
1
faction
2
region
Returns:
nil
-
cm:override_human_player_max_units(max unitsnumber) -
Overrides the maximum number of units a human player may have in their force. Pass any value at or below 0 to clear the override. This does not remove existing units if there are more than the cap in any player army.
Parameters:
1
max units
Returns:
nil
-
cm:add_or_remove_faction_features(factionfaction,feature listtable,should addboolean) -
Adds or removes a feature to or from the supplied faction. Valid feature keys may be found in the
faction_featuresdatabase table.Parameters:
1
Faction interface.
2
List of features to add or remove. This should be a table of
stringfeature keys, each from thefaction_featuresdatabase table.3
Add or remove the specified feature(s).
Returns:
boolean
-
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. Note that if the command is sent via the command queue thentruewill always be returned, regardless of whether the mission successfully triggers.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_custom_mission(faction keystring,mission keystring) -
Cancels an active custom mission.
Parameters:
1
Faction key, from the
factionstable.2
Mission key, from the
missionstable.Returns:
nil
-
cm:fail_custom_mission(faction keystring,mission keystring) -
Fails an active custom mission.
Parameters:
1
Faction key, from the
factionstable.2
Mission key, from the
missionstable.Returns:
nil
-
cm:trigger_mission_with_targets(faction cqi
number,mission 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 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:trigger_custom_incident_with_targets(faction cqi
number,fire immediately
boolean,incident payload
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 an incident 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 incident will need to pass any conditions set up in the
cdir_events_incidents_option_junctionsdatabase table in order to trigger.Parameters:
1
Command-queue index of the faction to which the incident is issued. This must be supplied.
2
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 incident data.
3
Payload string. Check
missions.txtfor examples of how to structure a payload string.4
Command-queue index of a target faction.
0may be specified to omit this target (and other target arguments following this one).5
Command-queue index of a second target faction. May be
0.6
Command-queue index of a target character. May be
0.7
Command-queue index of a target military force. May be
0.8
Command-queue index of a target region. May be
0.9
Command-queue index of a target settlement. May be
0.Returns:
nil
-
cm:mission_is_active_for_faction(factionfaction, missionkey) -
Checks whether the supplied faction has an active mission with the specified key.
Parameters:
1
Faction.
2
missionMission key, from the
missionsdatabase table.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. This functionality is used to empower features such as Ogre contracts, where several missions are created and the player selects from them.
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
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(faction name
string,mission key
string,script key
string,is success
boolean
) -
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
Name of the faction completing the mission, from the
factionsdatabase table.2
Mission key, from the
missionstable.3
Key of the particular scripted objective associated with the mission.
4
Objective was completed successfully.
Returns:
nil
-
cm:set_scripted_mission_entity_completion_states(mission keystring,script keystring,entitiestable) -
Sets the completion state for entities targeted by a scripted mission objective. These entities are target factions, settlements, characters etc that are shown on the mission panel and can be marked as completed when the entity in question has been captured/destroyed etc.
Entities can be specified as either completed or uncompleted. If an entity passed in to this function is not already present on the mission panel then it will be added.
This function can only be used for scripted missions i.e. missions of objective typeSCRIPTED, where script controls the completion conditions of the mission.Parameters:
1
Mission key, from the
missionsdatabase table.2
Key of the particular scripted objective associated with the mission.
3
Entity table. This should be a table containing one or more sub-tables in the form
{ {region, true}, {character, false} }. The first element of each sub-table is an interface object such asfactioninterface, and the second a boolean indicating whether it should be marked as completed or not on the UI.Returns:
nil
-
cm:remove_scripted_mission_entities(mission keystring,script keystring,entitiestable) -
Remove specified entity completion states that were previously added with
cm:set_scripted_mission_entity_completion_statesfrom a scripted mission objective. These entities are target factions, settlements, characters etc that are shown on the mission panel and can be marked as completed when the entity in question has been captured/destroyed etc.Parameters:
1
Mission key, from the
missionsdatabase table.2
Key of the particular scripted objective associated with the mission.
3
Entity table. This should be a table containing one or more interface objects to remove, in the form
{region, character, faction}.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("wh_main_emp_empire", "wh_main_test_incident", true, "payload{money 1000;}");
-
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_custom_dilemma_for_character(character lookup
string,dilemma key
string,first choice payload
string,second choice payload
string
) -
Triggers a custom dilemma with two choices, with the specified character as the dilemma target.
Parameters:
1
Character lookup string. For more information, see
Character Lookups.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 (the High Elf game mechanic) 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
The dilemma builder interface allows a dilemma to be constructed in script before being issued with cm:launch_custom_dilemma_from_builder. The function cm:create_dilemma_builder returns a campaign_dilemma_builder which can be used to construct the dilemma.
The same can be done with the incident builder interface. Constructed incidents are issued with cm:launch_custom_incident_from_builder. cm:create_incident_builder returns a campaign_incident_builder.
-
cm:create_dilemma_builder(dilemma keystring) -
Creates and returns an empty dilemma builder. Functions provided by the returned
campaign_dilemma_builderinterface can be used to create a new custom dilemma from script.Parameters:
1
Dilemma record key, from the
dilemmasdatabase table.Returns:
campaign_dilemma_builder
-
cm:launch_custom_dilemma_from_builder(dilemma buildercampaign_dilemma_builder,factionfaction) -
Launches a dilemma previously constructed with
cm:create_dilemma_builderfor the recipient faction.Parameters:
1
Dilemma builder interface.
2
Recipient faction interface.
Returns:
nil
-
cm:create_incident_builder(incident keystring) -
Creates and returns an empty incident builder. Functions provided by the returned
campaign_incident_builderinterface can be used to create a new custom incident from script.Parameters:
1
Incident record key, from the
incidentsdatabase table.Returns:
campaign_incident_builder
-
cm:launch_custom_incident_from_builder(incident buildercampaign_incident_builder,factionfaction) -
Launches an incident previously constructed with
cm:create_incident_builderfor the recipient faction.Parameters:
1
Incident builder interface.
2
Recipient faction interface.
Returns:
nil
-
cm:create_payload() -
Creates and returns a new payload builder. Functions provided by the
campaign_payload_builderinterface which can be used to create a new payload from script, which can be applied to created dilemmas.Returns:
campaign_payload_builder
-
cm:apply_payload(payloadcampaign_payload_builder,factionfaction) -
Directly applies a custom created payload to the specified faction. This can be used if it's desired to directly apply a created payload to the faction for some reason.
Parameters:
1
Custom payload, created with
cm:create_payload.2
Target faction interface.
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_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 disableboolean,categorystring,subcategorystring,eventstring) -
Enables or disables 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.
For each specifier type (category/subcategory/event), multiple specifiers may be supplied in a single string, separated by semicolons. A category string of"wh_event_category_agent;wh_event_category_character"will block/unblock all event messages related to agents and characters, for example.
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.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 event to block, from the
event_feed_eventstable. Supply a blank string to not filter by event.Returns:
nil
-
cm:region_slot_instantly_dismantle_building(slotslot) -
Instantly dismantle the building in the supplied region slot.
Parameters:
1
Slot script interface.
Returns:
nil
-
cm:region_slot_instantly_upgrade_building(slotslot,building keystring) -
Instantly upgrade the building in the supplied region slot to the supplied building. The building specified must be a valid upgrade for the building chain present in the slot.
Parameters:
1
Slot script interface.
2
Building key, from the
building_levelsdatabase table.Returns:
nil
-
cm:region_slot_instantly_repair_building(slotslot) -
Instantly repair the building in the specified slot.
Parameters:
1
Slot script interface.
Returns:
nil
-
cm:foreign_slot_instantly_dismantle_building(foreign slot cqinumber) -
Instantly dismantles the building in the specified foreign slot. The slot is specified by slot cqi, which can be obtained from the
foreign_slotscript interface on themodel_hierarchy.Parameters:
1
foreign slot cqi
Returns:
nil
-
cm:foreign_slot_instantly_upgrade_building(foreign slot cqinumber,building keystring) -
Instantly upgrades the building in the specified foreign slot. The slot is specified by slot cqi, which can be obtained from the
foreign_slotscript interface on themodel_hierarchy.Parameters:
1
Foreign slot cqi.
2
Building key, from the
building_levelstable.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: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: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:add_building_to_settlement(region keystring,building keystring,operation was successfulboolean) -
Attempts to add a building to a settlement. A slot must be available, or the settlement must contain a building that can be upgraded to the building specified.
Parameters:
1
Key of the region containing the target settlement, from the
campaign_map_regionstable.2
Building key, from the
building_levelstable.3
operation was successful
Returns:
nil
-
cm:add_building_to_settlement_queue(target slotslot,buildingstring) -
Adds a building to a settlement queue, by building slot.
Parameters:
1
Target slot script interface.
2
Building level key, from the
building_levelsdatabase table.Returns:
nil
-
cm:add_foreign_slot_set_to_region_for_faction(faction cqinumber,region cqinumber,slot set keystring) -
Adds the specified foreign slot set to the target region, for the target faction. The foreign slot manager of the faction is returned, or a null script interface if parameters are invalid.
Parameters:
1
Command-queue index value of the target faction.
2
Command-queue index value of the target region.
3
Slot set key, from the
slot_setstable.Returns:
foreign_slot_manager
-
cm:instantly_set_settlement_primary_slot_level() -
Instantly sets the primary slot level of the supplied settlement. The supplied level will be clamped to the maximum level of the chain. The new primary slot building will be returned.
Returns:
building
-
cm:get_building_level_upgrades(building keystring) -
Returns a lua table containing a list of building keys that are upgrades from a supplied building key. If the building specified by the supplied key has no upgrades then the returned table will be empty. If the supplied key does not specify a building then nothing is returned.
Building keys all specify building records in thebuilding_levelsdatabase table.Parameters:
1
building key
Returns:
table
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_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_character(effect bundlestring,charactercharacter,turnsnumber) -
Applies an effect bundle to a character.
Parameters:
1
Effect bundle key, from the
effect_bundlestable.2
Target 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 bundlestring,charactercharacter) -
Removes an effect bundle from a character.
Parameters:
1
Effect bundle key, from the
effect_bundlestable.2
Target character.
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_faction_province(effect bundlestring,regionregion,turnsnumber) -
Applies an effect bundle to a faction province. The faction province is specified by
regioninterface. The effect bundle will be applied to the portion of the province owned by the owner of the specified region - this can be the whole province if one faction controls it all.Parameters:
1
Effect bundle key, from the
effect_bundlestable.2
Region within the target faction province.
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_faction_province(effect bundlestring,regionregion) -
Removes an effect bundle from a faction province. The faction province is specified by
regioninterface. The effect bundle will be removed from the portion of the province owned by the owner of the specified region - this can be the whole province if one faction controls it all.Parameters:
1
Effect bundle key, from the
effect_bundlestable.2
Target region.
Returns:
nil
Custom effect bundles may be created, customised, and then applied to factions, regions, characters etc. custom_effect_bundle objects may be created and applied using the functions listed here.
-
cm:create_new_custom_effect_bundle(base effect bundlestring) -
Creates a new custom effect bundle, using the specified effect bundle record as a base.
Parameters:
1
Base effect bundle key, from the
effect_bundlestable.Returns:
custom_effect_bundle
-
cm:apply_custom_effect_bundle_to_region(custom effect bundlecustom_effect_bundle,regionregion) -
Applies a custom effect bundle to a region. This replaces any existing effect bundle with the same record.
Parameters:
1
custom effect bundle
2
region
Returns:
nil
-
cm:apply_custom_effect_bundle_to_faction(custom effect bundlecustom_effect_bundle,factionfaction) -
Applies a custom effect bundle to a faction. This replaces any existing effect bundle with the same record.
Parameters:
1
custom effect bundle
2
faction
Returns:
nil
-
cm:apply_custom_effect_bundle_to_character(custom effect bundle
custom_effect_bundle,character
character
) -
Applies a custom effect bundle to a character. This replaces any existing effect bundle with the same record.
Parameters:
1
custom effect bundle
2
character
Returns:
nil
-
cm:apply_custom_effect_bundle_to_force(custom effect bundle
custom_effect_bundle,military force
military_force
) -
Applies a custom effect bundle to a military force. This replaces any existing effect bundle with the same record.
Parameters:
1
custom effect bundle
2
military force
Returns:
nil
-
cm:apply_custom_effect_bundle_to_faction_province(custom effect bundle
custom_effect_bundle,region
region
) -
Applies a custom effect bundle to a province. This replaces any existing effect bundle with the same record. The effect bundle will be applied to the portion of the province owned by the owner of the specified region - this can be the whole province if one faction controls it all.
Parameters:
1
custom effect bundle
2
region
Returns:
nil
-
cm:apply_custom_effect_bundle_to_characters_force(custom effect bundle
custom_effect_bundle,character
character
) -
Applies a custom effect bundle to a character's military force. This replaces any existing effect bundle with the same record.
Parameters:
1
custom effect bundle
2
character
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^8peace 2^9war 2^10join war 2^11break trade 2^12break alliance 2^13hostages 2^14non aggression pact 2^15soft military access 2^16cancel soft military access 2^17defensive alliance 2^18client state 2^19form confederation 2^20break non aggression pact 2^21break soft military access 2^22break defensive alliance 2^23break vassal 2^24break client state 2^25state gift unilateral 2^26campaign_manager:force_diplomacyon thecampaign_managerinterface wraps this function, providing a more useable interface and debug output. It's recommended to call that function rather than directly calling this one.Parameters:
1
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
) -
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.
Returns:
nil
-
cm:force_make_vassal(vassalising faction keystring,vassal faction keystring) -
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.Returns:
nil
-
cm:force_alliance(first faction keystring,second faction keystring,is military allianceboolean) -
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.Returns:
nil
-
cm:force_grant_military_access(granting faction key
string,recipient faction key
string,is hard access
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.
Returns:
nil
-
cm:force_make_peace(first faction keystring,second faction keystring) -
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.Returns:
nil
-
cm:force_rebellion_with_faction(region
region,faction key
string,max units
number,full strength
boolean,suppress public order penalty
[boolean]
) -
Forces a rebellion by a specified faction of a specified size in a given region. If a rebellion force is spawned then it is returned.
Parameters:
1
Interface of the region in which to spawn rebellion force.
2
Faction key of the rebelling faction, from the
factionsdatabase table.3
Maximum number of units to spawn.
4
Spawn at full strength or not.
5
optional, default value=false
Set this argument to
truefor the rebellion to not affect public order in the target region.Returns:
military_force
-
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: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: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:lock_one_technology_node(faction keystring,technology keystring) -
Lock one technology node, without locking any of its children.
Parameters:
1
Faction key, from the
factionsdatabase table.2
Technology key, from the
technologiesdatabase table.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:update_technology_unlock_progress_values(faction key
string,technology key
string,progress values
table
) -
Updates the value of a design-driven unlock condition for a technology.
Designer-driven unlock conditions can be added to a technology through an entry in thetechnology_script_lock_reasonsdatabase table. A text condition specified in the added record is displayed when the cursor is placed over the related technology, such as"Win 5 Ambush battles.\nCurrent Amount: %d". This function may be used to update the text variable within the displayed string.
The function should also be used at the start of the campaign to set the initial condition of each design-driven technology unlock condition e.g. setting a counter to 0.
Note that this function does not unlock the technology when the condition is fully met. Usecm:unlock_technologyto unlock the technology at this time.Parameters:
1
Key of the faction owning the technology, from the
factionsdatabase table.2
Key of the technology, from the
technologiesdatabase table.3
Table of one or more values to insert into the technology progress string. Multiple values are supported where appropriate, e.g.
{3, 7}to update a string such as"Find all Snow White's Dwarfs.\nCurrent Amount: %d of %d".Returns:
nil
-
cm:instantly_research_technology(faction keystring,technology keystring,notify event feedboolean) -
Instantly completes research for the specified technology for the specified faction. An additional flag specifies whether to post a notification to the event feed.
Parameters:
1
Faction key, from the
factionstable.2
Technology key, from the
technologiestable.3
Send a notification to the event feed that the research is completed, or not.
Returns:
nil
-
cm:instantly_research_all_technologies(faction keystring) -
Instantly completes research on all technologies for the specified faction.
Parameters:
1
Faction key, from the
factionstable.Returns:
nil
-
cm:instantly_clear_all_technologies(faction keystring) -
Instantly resets all technologies for the specified faction to an unresearched state.
Parameters:
1
Faction key, from the
factionstable.Returns:
nil
-
cm:building_level_unlocks_technology_for_faction(factionfaction,building keystring) -
Returns whether the specified building level unlocks any technologies for the specified faction.
Parameters:
1
Faction interface.
2
Building level key, from the
building_levelsdatabase table.Returns:
boolean
-
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.
Note that theenable_scripted_pathfinding_restrictionscampaign variable must be set for restrictions to work - create an entry for this variable and the campaign in thecampaigns_campaign_variables_junctionstable.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: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:add_regular_pooled_resource_transaction(entity interface
interface,resource cost key
string,turns
number
) -
Adds a regular resource transaction to an entity such as a character, faction or province. This will cause the target entity to spend or earn a particular pooled resource at the start of a number of turns, or indefinitely. A record for the transaction must be defined in the database, in the
resource_coststable.Parameters:
1
interfaceInterface of entity to apply the pooled resource transaction to e.g.
character,faction.2
Key of the resource cost record to apply, from the
resource_costsdatabase table.3
Number of turns to apply the transaction for. If
0is supplied, the transaction is applied indefinitely.Returns:
nil
-
cm:remove_regular_pooled_resource_transaction(interfaceentity interface,resource cost keystring) -
Removes a specified regular resource transaction from an entity such as a character, faction or province. An empty key will remove all regular pooled resource transactions for the entity in the system.
Parameters:
1
interfaceInterface of entity to remove the pooled resource transaction from e.g.
province,military_force.2
Key of the resource cost record to remove, from the
resource_costsdatabase table. If a blank string is supplied then all resource costs are removed.Returns:
nil
-
cm:pooled_resource_transaction(resource managerpooled_resource_manager,resource cost keystring) -
Apply a transaction to a pooled resource manager. A record from the
resource_costsdatabase table is specified, which determines the factors and amounts of pooled resources to modify.Parameters:
1
Resource manager interface.
2
Key of the resource cost record to apply, from the
resource_costsdatabase table.Returns:
nil
-
cm:pooled_resource_factor_transaction(resource manager
pooled_resource_manager,resource factor key
string,amount
number
) -
Apply a transaction to a pooled resource manager. The single factor to change and amount to change it by are supplied as arguments.
Parameters:
1
Resource manager interface.
2
Key of the resource factor to change, from the
pooled_resource_factorsdatabase table.3
Change amount. This may be negative.
Returns:
nil
-
cm:apply_regular_reset_income(resource managerpooled_resource_manager) -
Apply regular pooled resoure income and expenditure on provided pooled resource manager.
Parameters:
1
Resource manager interface.
Returns:
nil
-
cm:force_winds_of_magic_change(area keystring,strength keystring) -
Forces a change in the winds of magic for a given area.
Parameters:
1
Winds of Magic area key, from the
campaign_map_winds_of_magic_areadatabase table.2
Winds of Magic strength key, from the
campaign_map_winds_of_magic_strengthsdatabase table.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 keystring,target faction keystring,ritual keystring) -
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
ritualstable.Returns:
nil
-
cm:create_new_ritual_setup(performing_factionfaction,ritual keystring) -
Creates and returns a new modify ritual setup interface, based on an existing ritual.
Parameters:
1
Faction to perform the ritual.
2
Ritual key, from the
ritualstable.Returns:
modify_ritual_setup
-
cm:perform_ritual_with_setup(setupmodify_ritual_setup) -
Perform a ritual with the provided setup. It must be available and valid for this call to succeed. Both modify and standard ritual setup interfaces are valid for this method.
Parameters:
1
Ritual setup to use. This may be either a mutable
modify_ritual_setupor immutableritual_setupobject.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:lock_ritual(factionfaction,ritual keystring) -
Lock a ritual for a faction.
Parameters:
1
Target faction interface.
2
Ritual key, from the
ritualstable.Returns:
nil
-
cm:unlock_ritual(factionfaction,ritual keystring,durationnumber) -
Unlock a ritual for a faction.
Parameters:
1
Target faction interface.
2
Ritual key, from the
ritualstable.3
Duration, number of rounds the ritual will be unlocked for. Zero or negative will be infinite.
Returns:
nil
-
cm:lock_ritual_chain(factionfaction,ritual_chain_keystring) -
Lock a ritual chain for a faction.
Parameters:
1
Target faction interface.
2
Ritual chain key, from the
ritual_chainstable.Returns:
nil
-
cm:unlock_ritual_chain(factionfaction,ritual chain keystring,durationnumber) -
Unlock a ritual chain for a faction.
Parameters:
1
Target faction interface.
2
Ritual Chain key, from the
ritual_chainstable.3
Duration, number of rounds the ritual chain will be unlocked for. Zero or negative will be infinite.
Returns:
nil
-
cm:lock_rituals_in_category(factionfaction,ritual_category_keystring) -
Lock all rituals in a category for a faction.
Parameters:
1
Target faction interface.
2
Ritual category key, from the
ritual_categoriestable.Returns:
nil
-
cm:unlock_rituals_in_category(factionfaction,ritual_category_keystring,durationnumber) -
Unlock rituals in a category for a faction.
Parameters:
1
Target faction interface.
2
Ritual category key, from the
ritual_categoriestable.3
Duration, number of rounds the rituals in the category will be unlocked for. Zero or negative will be infinite.
Returns:
nil
-
cm:apply_active_ritual(factionfaction,ritualactive_ritual) -
Applies the effect of a ritual that is active right now. This is used in conjunction with the
delay_payload_applicationfield of theritualsdatabase table. Should this field be set for a ritual, then that ritual will not apply its payload effects when triggered until this function orcm:apply_active_ritualsis called.
Calls to this function will not succeed if the ritual has not been actively triggered.Parameters:
1
Target faction interface.
2
Target ritual interface.
Returns:
nil
-
cm:apply_active_rituals(factionfaction) -
Applies the effect of all rituals that are active for a faction right now. This is used in conjunction with the
delay_payload_applicationfield of theritualsdatabase table. Should this field be set for a ritual, then that ritual will not apply its payload effects when triggered until this function orcm:apply_active_ritualis called.
Calls to this function will not succeed if the ritual has not been actively triggered.Parameters:
1
Target faction.
Returns:
nil
-
cm:spawn_plague_at_settlement(settlementsettlement,plague keystring) -
Spawn a plague at a settlement.
Parameters:
1
Target settlement.
2
Plague key, from the
plaguestable.Returns:
nil
-
cm:spawn_plague_at_region(regionregion,plague keystring) -
Spawn a plague in a region.
Parameters:
1
Target region.
2
Plague key, from the
plaguestable.Returns:
nil
-
cm:spawn_plague_at_military_force(military forcemilitary_force,plague keystring) -
Spawn a plague at a military force.
Parameters:
1
Target military force.
2
Plague key, from the
plaguestable.Returns:
nil
-
cm:set_military_force_plague(military forcemilitary_force,plague keystring) -
Sets the plague on a military force.
Parameters:
1
Target military force.
2
Plague key, from the
plaguestable.Returns:
nil
-
cm:cook_recipe(factionfaction,recipestring) -
Attempt to cook a recipe for a faction. The default ingredients will be used.
Parameters:
1
Faction interface.
2
Recipe to cook. This should be a key from the
cooking_recipesdatabase table.Returns:
boolean
-
cm:cook_recipe_with_ingredients(faction
faction,recipe
string,primary ingredients
table,secondary ingredients
table
) -
Attempt to cook a recipe for a faction with the specified ingredients. The ingredients lists should be specified as tables of strings.
Parameters:
1
Faction interface.
2
Recipe to cook. This should be a key from the
cooking_recipesdatabase table.3
Table containing a list of
stringvalues. Each should be a key from thecooking_ingredientsdatabase table.4
Table containing a list of
stringvalues. Each should be a key from thecooking_ingredientsdatabase table.Returns:
boolean
-
cm:force_cook_recipe(factionfaction,recipestring,apply costboolean) -
Force a recipe to be cooked for a faction. The default ingredients will be used.
Parameters:
1
Faction interface.
2
Recipe to cook. This should be a key from the
cooking_recipesdatabase table.3
Apply the recipe cost.
Returns:
boolean
-
cm:force_cook_recipe_with_ingredients(faction
faction,recipe
string,primary ingredients
table,secondary ingredients
table,apply cost
boolean
) -
Force a recipe to be cooked for a faction with the specified ingredients. The ingredients lists should be specified as tables of strings.
Parameters:
1
Faction interface.
2
Recipe to cook. This should be a key from the
cooking_recipesdatabase table.3
Table containing a list of
stringvalues. Each should be a key from thecooking_ingredientsdatabase table.4
Table containing a list of
stringvalues. Each should be a key from thecooking_ingredientsdatabase table.5
Apply the recipe cost.
Returns:
boolean
-
cm:unlock_cooking_ingredient(factionfaction,ingredientstring) -
Unlock an ingredient for a faction. The ingredient must be permitted for the faction.
Parameters:
1
Faction interface.
2
Ingredient key, from the
cooking_ingredientsdatabase table.Returns:
nil
-
cm:unlock_cooking_recipe(factionfaction,recipestring) -
Unlock a cooking recipe for a faction. The recipe must be permitted for the faction.
Parameters:
1
Faction interface.
2
Recipe key, from the
cooking_recipesdatabase table.Returns:
nil
-
cm:clear_active_cooking_recipe(factionfaction) -
Clears the active recipe for the specified faction.
Parameters:
1
Faction interface.
Returns:
boolean
-
cm:set_faction_max_primary_cooking_ingredients(factionfaction,max ingredientsnumber) -
Sets the maximum number of primary ingredients that the specified faction may cook with. This value is clamped between 0 and 10.
Parameters:
1
Faction interface.
2
Maximum number of ingredients.
Returns:
nil
-
cm:set_faction_max_secondary_cooking_ingredients(factionfaction,max ingredientsnumber) -
Sets the maximum number of secondary ingredients that the specified faction may cook with. This value is clamped between 0 and 10.
Parameters:
1
Faction interface.
2
Maximum number of ingredients.
Returns:
nil
The caravan system empowers the Cathay Ivory Road game feature. The functions in this section may be used to control caravan deployment and progress. See also the various caravan script interfaces provided by the model_hierarchy documentation such as caravans_system and caravan, and the related function cm:cai_insert_caravan_diplomatic_event documented elsewhere in this file.
-
cm:recruit_caravan(factionfaction,caravan recruitment itemcaravan_recruitment_item) -
Recruits the specified caravan recruitment item into the specified faction. If successful, a caravan script interface is returned.
Parameters:
1
Faction interface.
2
Caravan recruitment item interface.
Returns:
-
cm:start_caravan(factionfaction,family memberfamily_member,cargonumber,start noderoute_node) -
Start a character on a new caravan journey. If successful, the caravan script interface is returned.
Parameters:
1
Faction interface.
2
Family member interface of caravan master character.
3
Cargo value.
4
Starting node of journey.
Returns:
-
cm:set_caravan_cargo(caravancaravan,cargonumber) -
Set the cargo value of a caravan. The new cargo value that was set is returned - this can be different to the value passed in to this function if that value was out of bounds.
Parameters:
1
Caravan script interface.
2
Cargo value.
Returns:
number
-
cm:set_caravan_path(caravancaravan,path destinationroute_path) -
Set the path of a caravan. A boolean value indicating whether the path was successfully set is returned.
Parameters:
1
caravan
2
path destination
Returns:
boolean
-
cm:set_caravan_auto_path(caravancaravan,targetroute_position) -
Set the path of a caravan, auto-generating the best route to avoid banditry. A boolean value indicating whether the path was successfully set is returned.
Parameters:
1
caravan
2
target
Returns:
boolean
-
cm:clear_caravan_path(caravancaravan) -
Clears a caravan's current path. A boolean value indicating whether the path was successfully cleared is returned.
Parameters:
1
caravan
Returns:
boolean
-
cm:move_caravan(caravancaravan) -
Move a caravan to the next node on its current path. A boolean value indicating whether the movement was successful is returned.
Parameters:
1
caravan
Returns:
boolean
-
cm:set_region_caravan_banditry(regionregion_data,banditry valuenumber) -
Set the banditry value for a region. The value that was set is returned - this can be different to the value passed in to this function if that value was less than zero or higher than the maximum banditry value set in the
campaign_variablesdatabase table (or thecampaigns_campaign_variables_junctionsoverride table).Parameters:
1
region
2
banditry value
Returns:
number
-
cm:set_multi_region_caravan_banditry(regionstable,banditry valuenumber) -
Set the banditry value for multiple regions, supplied as
region_dataobjects in a lua table.Parameters:
1
Table of
region_dataobjects.2
banditry value
Returns:
nil
Teleportation networks allow designers to create multiple nodes on the campaign map between which player armies may teleport. See also the various teleportation network interfaces provided by the model_hierarchy documentation such as teleportation_network_system and teleportation_node.
-
cm:teleportation_network_open_node(node keystring, [template keystring]) -
Opens a specific teleportation node. The template key may be omitted if one is already defined in the
teleportation_network_nodesrecord in the database, otherwise it's required.Parameters:
1
Node record key, from the
teleportation_network_nodesdatabase table.2
optional, default value=nil
Teleportation network node template key, from the
teleportation_node_templatesdatabase table. This only needs to be provided if the node record specified in the first argument does not provide a template.Returns:
boolean
-
cm:teleportation_network_close_node(node keystring) -
Closes a specified teleportation node.
Parameters:
1
Node record key, from the
teleportation_network_nodesdatabase table.Returns:
nil
-
cm:teleportation_network_open_random_nodes(network keystring,template keystring,nodes to opennumber) -
Opens random nodes in a given teleportation network with the specified template type. The number of nodes opened is returned.
Parameters:
1
Node network key, from the
teleportation_networksdatabase table.2
Node template key of nodes to open, from the
teleportation_node_templatesdatabase table.3
Target number of nodes to open.
Returns:
number
-
cm:teleportation_network_close_random_nodes(network key
string,template key
string,nodes to close
number
) -
Closes random nodes in a teleportation network with a specific template type. The number of nodes closed is returned.
Parameters:
1
Node network key, from the
teleportation_networksdatabase table.2
Node template key of nodes to open, from the
teleportation_node_templatesdatabase table.3
Target number of nodes to close.
Returns:
number
-
cm:teleportation_network_close_all_nodes(network keystring, [template keystring]) -
Closes all nodes in a teleportation network with a specific template type. The template type may be omitted in order to close the entire network.
Parameters:
1
Node network key, from the
teleportation_networksdatabase table.2
optional, default value=nil
Node template key of nodes to close, from the
teleportation_node_templatesdatabase table.Returns:
nil
-
cm:teleportation_network_set_effect_level_modifier(network keystring,modifiernumber) -
Set an effect level modifier to be applied to the nodes of a given teleportation network.
Parameters:
1
Node network key, from the
teleportation_networksdatabase table.2
Modifier value.
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:set_next_winds_of_magic_compass_selection_cooldown(factionfaction,turnsnumber) -
Sets the cooldown in turns before the compass heading may be changed for the specified faction.
Parameters:
1
Faction interface.
2
Number of turns before the faction may alter the compass direction.
Returns:
nil
-
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_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:faction_purchase_unit_effect(factionfaction,unitunit,purchasable effectunit_purchasable_effect) -
Makes the supplied faction purchase a supplied effect for a supplied unit. Unit purchasable effects are upgrades for units, which is supported for some factions/races.
Parameters:
1
faction
2
unit
3
purchasable effect
Returns:
nil
-
cm:faction_unpurchase_unit_effect(unitunit,purchasable effectunit_purchasable_effect) -
Makes the supplied faction unpurchase a supplied effect for a supplied unit, marking the effect as purchasable again. See also
cm:faction_purchase_unit_effect.Parameters:
1
unit
2
purchasable effect
Returns:
nil
-
cm:faction_set_unit_purchasable_effect_lock_state(faction
faction,purchasable effect
string,lock reason
string,should lock
boolean
) -
Locks or unlocks the purchasable unit effect faction-wide, with an optional lock reason record.
Parameters:
1
Faction interface.
2
Unit purchasable effect. This should be a key from the
unit_purchasable_effectsdatabase table.3
Lock reason. This should be a key from the
unit_purchasable_effect_lock_reasonsdatabase table. A blank string may be supplied to not provide a lock reason.4
Should lock - supply
trueto lock the effect, andfalseto unlock it.Returns:
nil
-
cm:faction_imprison_character(imprisoning factionfaction,imprisoned charactercharacter) -
Puts the supplied character into the supplied faction's prison.
Parameters:
1
imprisoning faction
2
imprisoned character
Returns:
nil
-
cm:faction_perform_action_on_prisoner(factionfaction,characterfamily_member,actionstring) -
Performs an action on a character within the faction's prison.
Parameters:
1
Imprisoning faction.
2
Family member interface related to the imprisoned character.
3
Action to perform. This should be a key from the
campaign_prison_actionsdatabase table.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
) -
Adds a record which modifies or completely overrides a fought or autoresolved battle, 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.
Note that thecampaign_managerintercepts calls which modify custom battlefield records, and will defer them if a battle is currently active and has been fought. This is to stop existing custom battlefield records, which are needed by the code to process the battle result, from being tampered with. See theCustom Battlefieldssection.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.Returns:
nil
-
cm:remove_custom_battlefield(idstring) -
Removes a custom battle override previously set with
cm:add_custom_battlefield.
Note that thecampaign_managerintercepts calls which modify custom battlefield records, and will defer them if a battle is currently active and has been fought. This is to stop existing custom battlefield records, which are needed by the code to process the battle result, from being tampered with. See theCustom Battlefieldssection.Parameters:
1
id
Returns:
nil
-
cm:clear_custom_battlefields() -
Removes all custom battle overrides previously set with
cm:add_custom_battlefield.
Note that thecampaign_managerintercepts calls which modify custom battlefield records, and will defer them if a battle is currently active and has been fought. This is to stop existing custom battlefield records, which are needed by the code to process the battle result, from being tampered with. See theCustom Battlefieldssection.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: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: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:pending_battle_add_scripted_tile_upgrade_tag(tile upgrade keystring) -
Adds the specified tile upgrade to the currently active pending battle. This should match the key of a tile upgrade set within the map data of the tile the battle will be fought on, so its use is highly situational.
The function will only work if called while the pending battle is being set up.Parameters:
1
tile upgrade key
Returns:
boolean
-
cm:pending_battle_remove_scripted_tile_upgrade_tags(tile upgrade keystring) -
Removes the specified tile upgrade from the currently active pending battle. The function will only work if called while the pending battle is being set up.
Parameters:
1
tile upgrade key
Returns:
boolean
-
cm:set_battle_lighting_env_override(stringfile_name) -
Override the battle environment of upcoming battles. This needs to be cleared by calling it without any parameters.
Parameters:
1
stringThe file path of the battle environment file. E.g. "weather/battle/wh_day_clear_02.environment_group"
Returns:
nil
-
cm:update_pending_battle() -
Rebuild pending battle setup and autoresolve results. This should be called after any model modification, when processing the
PendingBattleevent.Returns:
nil
-
cm:set_prebattle_display_configuration_override(distance
number,height
number,bearing
number,scale
number,scale
number
) -
Set an override for the prebattle display camera configuration. This allows the camera to be positioned in a custom manner on the pre-battle screen.
Parameters:
1
Camera distance.
2
Camera height.
3
Bearing from camera to target in radians.
4
Unary scale of army leaders.
5
Separation of army leaders.
Returns:
nil
-
cm:set_prebattle_display_configuration_camera_type_override(camera typestring) -
Set an override for the prebattle display camera configuration type. Valid values are
"character","settlement"and"tunnel".Parameters:
1
camera type
Returns:
nil
-
cm:clear_prebattle_display_configuration_override() -
Clears any prebattle display configuration overrides previously set with
cm:set_prebattle_display_configuration_overrideorcm:set_prebattle_display_configuration_camera_type_override.Returns:
nil
-
cm:set_loading_screen_id(loading screen idstring) -
Sets a custom loading screen layout, altering the loading screen that is used to load out of this campaign into battle. The supplied argument should be the filename of a json file found in
data\UI\loading_ui\dynamic_loading_screen_data.Parameters:
1
loading screen id
Returns:
nil
Character observation options determine what gets shown during the end-turn sequence. Options such as whether the camera should follow the movements of allied or enemy characters may be set on an observation_options object. These objects are retrieved from a world interface:
observation_options_for_factionobservation_options_for_alliesobservation_options_for_enemiesobservation_options_for_neutrals
Functions may be called on these objects to customise them, and then the objects themselves may be supplied as arguments to one of the functions below. Only at this point are the options applied.
-
cm:set_character_observation_options_for_faction(subject faction
faction,observation options
observation_options
) -
Sets character observation options for a specific faction. The
observation_optionsmay be retrieved by callingobservation_options_for_factionon aworldinterface, and calling functions on it to customise view options before passing it back to this function.Parameters:
1
subject faction
2
observation options
Returns:
nil
-
cm:set_character_observation_options_for_allies(observation optionsobservation_options) -
Sets character observation options for all allies. The
observation_optionsmay be retrieved by callingobservation_options_for_allieson aworldinterface, and calling functions on it to customise view options before passing it back to this function.Parameters:
1
observation options
Returns:
nil
-
cm:set_character_observation_options_for_enemies(observation optionsobservation_options) -
Sets character observation options for all enemies. The
observation_optionsmay be retrieved by callingobservation_options_for_enemieson aworldinterface, and calling functions on it to customise view options before passing it back to this function.Parameters:
1
observation options
Returns:
nil
-
cm:set_character_observation_options_for_neutrals(observation optionsobservation_options) -
Sets character observation options for all neutral factions. The
observation_optionsmay be retrieved by callingobservation_options_for_neutralson aworldinterface, and calling functions on it to customise view options before passing it back to this function.Parameters:
1
observation options
Returns:
nil
-
cm:award_achievement(achievement keystring) -
Awards an achievement to the local player.
Parameters:
1
Achievement key, from the
achievementsdatabase table.Returns:
nil
-
cm:war_coordination() -
Returns a
war_coordination, through which war co-ordination queries are made and by which war co-ordination requests can be made.Returns:
war_coordination
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:set_base_strategic_threat_score(faction interfacefaction,threat scorenumber) -
Set the base strategic threat score for a faction. This corresponds to score levels seen in the
faction_strategic_threat_levelsdatabase table.Parameters:
1
faction interface
2
threat score
Returns:
nil
-
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: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_diplomatic_event(originating factionstring,target factionstring,diplomatic actionstring) -
Creates a diplomatic event that modifies the diplomatic standing between two factions. Example events include army trespassing, financial gifts, hostile agent actions etc.
Parameters:
1
Key of the faction the diplomatic event is originating from, from the
factionsdatabase table.2
Key of the faction the diplomatic event is targeting, from the
factionsdatabase table.3
Key of the diplomatic action, from the
cai_personality_diplomatic_eventsdatabase table.Returns:
nil
-
cm:cai_insert_caravan_diplomatic_event(event faction namestring,caravan faction namestring) -
Inserts a diplomatic event for a caravan arriving for a given faction.
Parameters:
1
Name of the faction receiving the diplomatic event, from the
factionsdatabase table.2
Name of the faction owning the caravan, from the
factionsdatabase table.Returns:
nil
-
cm:cai_disable_targeting_against_settlement(settlement keystring) -
Disables the ability of the ai to target a settlement.
Parameters:
1
Settlement key, from the
campaign_map_settlementsdatabase table.Returns:
nil
-
cm:cai_enable_targeting_against_settlement(settlement keystring) -
Enables the ability of the ai to target a settlement after it was disabled with
cm:cai_disable_targeting_against_settlement.Parameters:
1
Settlement key, from the
campaign_map_settlementsdatabase table.Returns:
nil
-
cm:cai_evaluate_quick_deal_action(proposing factionfaction,recipient factionfaction,deal typestring) -
Evaluates a quick-deal action between two factions, and returns both the quick deal score and whether the deal can be proposed. A quick deal score greater than zero means it would likely be accepted by the target faction (if controlled by the AI).
Parameters:
1
proposing faction interface.
2
recipient faction interface.
3
Deal type, from the
diplomatic_actionsdatabase table.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
Point of interest markers can be used to tell the AI about important locations on the map. The AI system may be set in data to act in certain ways in response to POI markers based on the numeric group id.
-
cm:cai_add_point_of_interest_generic_marker(poi group id
number,poi id
number,x
number,y
number,faction key
[string]
) -
Adds a point of interest marker for the AI. An optional associated faction can be specified.
Parameters:
1
point-of-interest group identifier index.
2
point-of-interest identifier index. This is the id within the group the POI belongs to.
3
Logical x co-ordinate.
4
Logical y co-ordinate.
5
optional, default value=nil
Key of associated faction, from the
factionsdatabase table.Returns:
nil
-
cm:cai_remove_point_of_interest_generic_marker(poi group idnumber,poi idnumber) -
Removes a point-of-interest marker based on its group id and id.
Parameters:
1
point-of-interest group identifier index.
2
point-of-interest identifier index.
Returns:
nil