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.

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

Loaded in Campaign Loaded in Campaign
Loaded in Battle Loaded in Battle
Loaded in Frontend Loaded in Frontend
Back to top

Creation and Usage

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

Example - Specification:

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

Character Lookups

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

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

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

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

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

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

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

cm:zero_action_points("character_cqi:45")

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

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

General Querying

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

Returns:

  1. boolean is new game

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 60

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

Returns:

  1. boolean is benchmark mode

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 65

cm:is_replay()
Returns whether this a campaign replay.

Returns:

  1. boolean is replay

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 70

cm:is_cinematic_editor_attached()
Returns whether the cinematic editor tool is currently attached to the game.

Returns:

  1. boolean is cinematic editor attached

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 75

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

Returns:

  1. model campaign model

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 80

cm:filesystem_lookup(string path)

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

Parameters:

1

string

path

Returns:

  1. string file list

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 85

cm:compare_localised_string(uicomponent uicomponent, string label string)

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

Parameters:

1

uicomponent

uicomponent

2

string

label string

Returns:

  1. boolean localisation matches

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

cm:is_dlc_flag_enabled(string dlc product key, string player faction key)

Returns whether the dlc with the specified key is activated for the given player, specified by faction.

Parameters:

1

string

dlc product key

2

string

player faction key

Returns:

  1. dlc flag enabled for this faction

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 98

Back to top

Saving and Loading

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

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

Parameters:

1

string

Value name.

2

data

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

3

context

context object

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 117

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

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

Parameters:

1

string

Value name.

2

data

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

3

context

context object

Returns:

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

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 125

cm:disable_saving_game(boolean should disable)

Prevents or allows the saving of the game.

Parameters:

1

boolean

should disable

Returns:

  1. nil

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

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 139

Back to top

Time Triggers

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

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

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

Parameters:

1

string

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

2

number

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

3

boolean

optional, default value=false

Repeats the time trigger if set to true.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 153

cm:remove_time_trigger(string id)

Removes a time trigger by string id.

Parameters:

1

string

id

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 160

Back to top

Advisor and Audio

cm:dismiss_advice()
Dismisses the advisor panel.

Returns:

  1. nil

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

cm:dismiss_advice_at_end_turn(boolean should dismiss)

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

Parameters:

1

boolean

should dismiss

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 180

cm:trigger_campaign_vo(string sound event, string character lookup, number delay)

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

string

Sound event name.

2

string

Character lookup string - see Character Lookups for more information.

3

number

Delay in seconds before triggering the vo.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 185

cm:stop_campaign_vo(string sound event)

Stops a playing campaign voiceover sound event.

Parameters:

1

string

Sound event name.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 192

cm:stop_campaign_advisor_vo()
Stops any playing campaign advisor voiceover.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 197

cm:trigger_2d_ui_sound(string sound event, number delay)

Triggers a sound event in 2D, so that it appears to play behind the camera.

Parameters:

1

string

Sound event name.

2

number

Delay before playing the sound, in ms.

Returns:

  1. nil

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

cm:stop_2d_ui_sound(string sound event)

Stops a playing 2D sound event by name.

Parameters:

1

string

Sound event name.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 207

cm:activate_music_trigger(string trigger name, string trigger argument)

Activates a trigger within the music system. A string argument must also be supplied.

Parameters:

1

string

trigger name

2

string

trigger argument

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 212

cm:set_music_paused(boolean pause)

Pauses or unpauses any playing music.

Parameters:

1

boolean

Pause the music. If false is specified then the music is unpaused.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 218

cm:set_global_vo_argument(string state group, string state)

Sets a VO state that can be used to alter what VO will play.

Parameters:

1

string

state group

2

string

state

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 223

cm:contextual_vo_enabled(boolean enable contextual vo)

Enables or disables contextual VO sounds. By default contextual vo is enabled - use this function to disable it.

Parameters:

1

boolean

enable contextual vo

Returns:

  1. nil

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

cm:add_character_actor_group_override(character character, string actor vo record key)

Override the actor of the desired character with an actor id from the provided actor group record.

Parameters:

1

character

Character interface.

2

string

Actor VO record key, from the audio_vo_actors database table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 234

Back to top

Camera

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

  1. display x co-ordinate of camera target

  2. display y co-ordinate of camera target

  3. horizontal distance from target to camera

  4. horizontal bearing in radians of target from camera

  5. height of camera

Example - scroll_camera_with_direction usage:

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

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

Repositions the camera to the specified co-ordinates.

Parameters:

1

number

Display x co-ordinate of camera target.

2

number

Display y co-ordinate of camera target.

3

number

Horizontal distance from camera to target.

4

number

Horizontal bearing in radians of target from camera.

5

number

Height of camera.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 257

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

Returns:

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

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

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

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

Parameters:

1

boolean

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

2

number

Scroll time in seconds

3

vararg

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 275

cm:stop_camera()
Stops a scrolling camera.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 282

cm:fade_scene(number brightness, number duration)

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

Parameters:

1

number

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

2

number

Duration of the fade effect in seconds.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 286

cm:enable_camera_bearing_clamp(number min rotation, number max rotation)

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

number

Minimum rotation value in radians. A value less than zero is permissable.

2

number

Maximum rotation value in radians.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 292

cm:disable_camera_bearing_clamp(number min rotation, number max rotation)

Disables a yaw rotation clamp previously enabled with cm:enable_camera_bearing_clamp.

Parameters:

1

number

Minimum rotation value in radians. A value less than zero is permissable.

2

number

Maximum rotation value in radians.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 298

cm:set_camera_height(number height)

Immediately sets the camera height.

Parameters:

1

number

height

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 304

cm:set_camera_minimum_height(number height)

Sets a minimum height for the camera.

Parameters:

1

number

height

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 309

cm:set_camera_maximum_height(number height)

Sets a minimum height for the camera.

Parameters:

1

number

height

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 314

Back to top

Movies and Cinematics

cm:register_instant_movie(string movie path)

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

Parameters:

1

string

movie path

Returns:

  1. nil

Example:

-- play the movie file data/Movies/Warhammer/chs_rises
cm:register_instant_movie("Warhammer/chs_rises")

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 327

cm:register_outro_movie(string movie path)

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

Parameters:

1

string

movie path

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 334

cm:play_movie_in_ui(string movie path)

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

Parameters:

1

string

movie path

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 339

cm:cinematic()
Returns a cinematic script interface.

Returns:

  1. cinematics cinematic interface

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 344

Back to top

Ending Turn

cm:end_turn([boolean force])

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

Parameters:

1

boolean

optional, default value=false

force

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 361

cm:end_turn_for_faction(faction faction)

Ends the turn for the specified faction.

Parameters:

1

faction

faction

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 366

cm:set_ai_uses_human_display_speed(boolean use human speed)

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

Parameters:

1

boolean

use human speed

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 371

cm:disable_end_turn(boolean should disable)

Disables or re-enables the local player's ability to end the turn.

Parameters:

1

boolean

should disable

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 376

cm:set_skip_faction_turn(faction faction, boolean should skip)

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

faction

2

boolean

should skip

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 381

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:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 387

cm:unskip_all_factions()
Restore the turn of every faction in the game, undoing any skipping behaviour previously set with cm:set_skip_faction_turn or cm:skip_all_ai_factions.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 391

Back to top

UI Manipulation

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

Activates or deactivates a ui override.

Parameters:

1

string

ui override name

2

boolean

activate override

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 408

cm:stop_user_input(boolean stop input)

Stops or allows user input.

Parameters:

1

boolean

stop input

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 414

cm:steal_user_input(boolean steal input)

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

Parameters:

1

boolean

steal input

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 419

cm:steal_escape_key(boolean steal escape key)

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

Parameters:

1

boolean

steal escape key

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 424

cm:enable_ui(boolean enable ui)

Enables or disables the user interface.

Parameters:

1

boolean

enable ui

Returns:

  1. nil

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

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

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

Parameters:

1

string

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

2

string

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

3

boolean

Should disable.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 434

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

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

Parameters:

1

string

Character lookup string - see Character Lookups for more information.

2

string

Model key, from the campaign_character_art_sets database table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 441

cm:add_character_model_override(character character, string model key)

Swap a model for a specific character. Same as add_unit_model_overrides, but doesn't use the character lookup.

Parameters:

1

character

Character interface.

2

string

Model key, from the campaign_character_art_sets database table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 447

cm:toggle_character_hidden_from_view(character character, boolean hide)

Hides or unhides a character from the view.

Parameters:

1

character

character

2

boolean

hide

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 453

cm:highlight_movement_extents(boolean should highlight)

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

Parameters:

1

boolean

should highlight

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 459

cm:set_army_outer_movement_extents_rendering_disabled(boolean should disable)

Globally disable or enable army movement extents from rendering.

Parameters:

1

boolean

should disable

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 464

cm:highlight_selected_character_zoc(boolean should highlight)

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

Parameters:

1

boolean

should highlight

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 469

Back to top

Markers, VFX and Composite Scenes

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

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

Parameters:

1

string

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

2

string

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

3

number

x display position.

4

number

y display position.

5

number

height above water plane.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 483

cm:remove_marker(string marker id)

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

Parameters:

1

string

marker id

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 492

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

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

Parameters:

1

string

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

2

string

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

3

number

Logical x position for the marker.

4

number

Logical y position for the marker.

5

number

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

6

string

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

7

string

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 497

cm:remove_interactable_campaign_marker(string unique id)

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

Parameters:

1

string

unique id

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 510

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

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

Parameters:

1

string

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

2

string

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

3

number

x display position.

4

number

y display position.

5

number

height above water plane.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 515

cm:remove_vfx(string vfx id)

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

Parameters:

1

string

vfx id

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 524

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

Adds a vfx to a specified character.

Parameters:

1

number

Command queue index of the character.

2

string

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

3

boolean

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 529

cm:remove_character_vfx(number character cqi, string vfx)

Removes a vfx from a specified character.

Parameters:

1

number

Command queue index of the character.

2

string

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 536

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

Adds a vfx to a specified garrison residence/settlement.

Parameters:

1

number

Command queue index of the garrison residence.

2

string

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

3

boolean

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 542

cm:remove_garrison_residence_vfx(number character cqi, string vfx)

Removes a vfx from a specified character.

Parameters:

1

number

Command queue index of the character.

2

string

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 549

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

Adds a composite scene at a specified logical position.

Parameters:

1

string

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

2

string

Composite scene key from the campaign_composite_scenes table.

3

number

Logical x co-ordinate.

4

number

Logical y co-ordinate.

5

number

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

6

number

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

7

boolean

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

8

boolean

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

9

boolean

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

10

faction

optional, default value=nil

Faction this composite scene is visible to. Defaults to all factions if not set.

Returns:

  1. boolean action successful

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 555

cm:add_scripted_composite_scene_to_settlement(
  string name,
  string composite scene,
  region region,
  number facing x,
  number facing y,
  boolean one shot,
  boolean show in seen shroud,
  boolean show in unseen shroud,
  [faction faction]
)

Adds a composite scene to a specified settlement.

Parameters:

1

string

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

2

string

Composite scene key from the campaign_composite_scenes table.

3

region

region of the settlement to add the scene to

4

number

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

5

number

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

6

boolean

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

7

boolean

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

8

boolean

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

9

faction

optional, default value=nil

Faction this composite scene is visible to. Defaults to all factions if not set.

Returns:

  1. boolean action successful

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 570

cm:add_scripted_composite_scene_to_settlement_port(
  string name,
  string composite scene,
  region Region,
  number facing x,
  number facing y,
  boolean one shot,
  boolean show in seen shroud,
  boolean show in unseen shroud,
  [faction faction]
)

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

Parameters:

1

string

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

2

string

Composite scene key from the campaign_composite_scenes table.

3

region

Region of the settlement to add the scene to

4

number

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

5

number

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

6

boolean

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

7

boolean

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

8

boolean

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

9

faction

optional, default value=nil

Faction this composite scene is visible to. Defaults to all factions if not set.

Returns:

  1. boolean action successful

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 584

cm:remove_scripted_composite_scene(string name)

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

Parameters:

1

string

name

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 598

Back to top

Shroud

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

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

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

  • Visible regions are fully displayed.

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

cm:show_shroud(boolean show)

Enables or disables the shroud.

Parameters:

1

boolean

show

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 618

cm:reset_shroud([faction faction])

Resets the shroud of a specified faction. If no faction is specified, the shrouds of all factions are reset.

Parameters:

1

faction

optional, default value=nil

faction

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 623

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

Returns:

  1. nil

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

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 632

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

Returns:

  1. nil

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

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 640

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

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

Parameters:

1

string

Faction key, from the factions table.

2

string

Region key, from the campaign_map_regions table.

Returns:

  1. nil

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

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

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

Parameters:

1

string

Faction key, from the factions table.

2

string

Region key, from the campaign_map_regions table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 650

cm:make_sea_region_visible_in_shroud(string region key)

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

Parameters:

1

string

Region key, from the campaign_map_regions table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 656

cm:make_sea_region_seen_in_shroud(string region key)

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

Parameters:

1

string

Region key, from the campaign_map_regions table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 661

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

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

Parameters:

1

string

player faction key

2

string

ai faction key

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 666

cm:disable_shopping_for_ai_under_shroud(boolean should disable)

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

Parameters:

1

boolean

should disable

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 672

cm:force_terrain_patch_visible(string patch)

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

string

Terrain patch key, from the campaign_terrain_patch_areas database table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 677

cm:reset_forced_terrain_patch_visibility()
Resets all terrain patch visility changes previously made with cm:force_terrain_patch_visible.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 682

cm:grant_faction_additional_vision(faction faction, region_data region data, [number duration])

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

Faction interface.

2

region_data

Region data interface.

3

number

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:

  1. nil

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

cm:remove_faction_additional_vision(faction faction, region_data region 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_vision then nothing will happen.

Parameters:

1

faction

Faction interface.

2

region_data

Region data interface.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 693

Back to top

Shared States

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([object object], string key, value value)

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

object

optional, default value=nil

Interface object to associate the shared value with. This argument may be omitted.

2

string

Key of shared value to set.

3

value

Value to set. Supported value types are boolean, number and string.

Returns:

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

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 713

cm:remove_script_state([object object], string key)

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

object

optional, default value=nil

Interface object to associate the shared value with. This argument may be omitted.

2

string

Key of shared value to set.

Returns:

  1. nil

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

Back to top

Character and Military Force Creation

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

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

Parameters:

1

string

Faction key from the factions table.

2

string

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

3

string

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

4

number

Logical x co-ordinate.

5

number

Logical y co-ordinate.

6

string

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

7

boolean

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

Returns:

  1. nil

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

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

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

Parameters:

1

string

Faction key from the factions table.

2

string

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

3

string

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

4

number

Logical x co-ordinate.

5

number

Logical y co-ordinate.

6

string

Character type key, from the agents table.

7

string

Character subtype key, from the agent_subtypes table.

8

string

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

9

string

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

10

string

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

11

string

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

12

string

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

13

boolean

Make this character the faction leader.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 749

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

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

Parameters:

1

string

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

2

string

Faction key from the factions table.

3

string

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

4

string

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

5

number

Logical x co-ordinate.

6

number

Logical y co-ordinate.

7

string

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 766

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

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

Parameters:

1

string

Faction key from the factions table.

2

string

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

3

string

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

4

number

Logical x co-ordinate.

5

number

Logical y co-ordinate.

6

string

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

7

boolean

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 777

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

Create an agent/hero character at a specified position.

Parameters:

1

string

Faction key from the factions table.

2

string

Agent type from the agents table.

3

string

Agent subtype from the agent_subtypes table.

4

number

Logical x co-ordinate.

5

number

Logical y co-ordinate.

6

string

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 789

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

Spawns an agent of the specified type at the specified logical position.

Parameters:

1

faction

Faction interface for the agent's faction.

2

number

x logical co-ordinate.

3

number

y logical co-ordinate.

4

string

Agent type key, from the agents table.

5

string

optional, default value=""

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 799

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

Spawns an agent of the specified type next to the specified settlement.

Parameters:

1

faction

Faction interface for the agent's faction.

2

settlement

Settlement at which to spawn the agent.

3

string

Agent type key, from the agents table.

4

string

optional, default value=""

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 808

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

Spawns an agent of the specified type next to the specified military force.

Parameters:

1

faction

Faction interface for the agent's faction.

2

military_force

Military force at which to spawn the agent.

3

string

Agent type key, from the agents table.

4

string

optional, default value=""

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 816

cm:embed_agent_in_force(character agent, military_force military force)

Instantly embed the specified agent in the specified force. The agent will teleport into the force, disregarding normal restrictions other than that force being under siege.

Parameters:

1

character

agent

2

military_force

military force

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 824

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

Creates a unique agent.

Parameters:

1

number

Faction cqi.

2

string

Agent record key, from the unique_agents table.

3

boolean

Force agent to spawn even if invalid.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 830

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

Creates a unique agent in a specified region.

Parameters:

1

number

Faction cqi.

2

string

Agent record key, from the unique_agents table.

3

number

The cqi of the target region.

4

boolean

Force agent to spawn even if invalid.

Returns:

  1. nil

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

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

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

Parameters:

1

number

Faction cqi.

2

string

Agent record key, from the unique_agents table.

3

number

The cqi of the target character.

4

boolean

Force agent to spawn even if invalid.

Returns:

  1. nil

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

cm:spawn_rogue_army(number x, number y)

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

Parameters:

1

number

Logical x co-ordinate.

2

number

Logical y co-ordinate.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 853

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

Spawns a new character in the specified faction's recruitment pool. The character_details interface related to the spawned character is returned.

Parameters:

1

string

Faction key, from the factions table.

2

string

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

3

string

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

4

string

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

5

string

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

6

number

Age of character.

7

boolean

Set this character to be male or female.

8

string

Agent record key, from the agents table.

9

string

Agent subtype key, from the agent_subtypes table.

10

boolean

Sets whether this character is immortal.

11

string

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

Returns:

  1. character_details character details interface

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 860

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

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

Parameters:

1

string

Faction key, from the factions table.

2

string

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

3

string

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

4

string

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

5

string

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

6

number

Age of character.

7

boolean

Set this character to be male or female.

8

string

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

9

string

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

10

boolean

Sets whether this character is immortal.

11

string

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

12

boolean

Make this character the faction heir.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 876

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

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

Parameters:

1

string

Faction key, from the factions table.

2

string

Region key of settlement, from the campaign_map_regions table.

3

boolean

Specifies whether the position should be on the sea.

4

boolean

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

5

number

optional, default value=0

Specifies the distance at which the character should spawn.

Returns:

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

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 892

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

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

Parameters:

1

string

Faction key, from the factions table.

2

number

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

3

number

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

4

boolean

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

5

number

optional, default value=0

Preferred spawn distance, in logical hexes.

Returns:

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

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

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

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

Parameters:

1

string

Faction key, from the factions table.

2

string

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

3

boolean

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

4

number

optional, default value=0

Preferred spawn distance, in logical hexes.

Returns:

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

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 914

cm:appoint_character_to_most_expensive_force(string character lookup)

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

Parameters:

1

string

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

Returns:

  1. nil

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

cm:appoint_character_to_force(string character lookup, number military force cqi)

Appoints the specified character to the command of the specified military force.

Parameters:

1

string

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

2

number

Command-queue index of target military force.

Returns:

  1. nil

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

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

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

string

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

2

string

Faction key of the character, from the factions table.

Returns:

  1. nil

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

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

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

string

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

2

string

Faction key of the character, from the factions table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 941

Back to top

Character and Force Manipulation

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

cm:replace_general_in_force(military_force military force, string agent subtype)

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

Military force interface.

2

string

Agent subtype key, from the agent_subtypes database table.

Returns:

  1. character created character

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

cm:add_agent_experience(string character lookup, number points)

Adds experience points to a specified character.

Parameters:

1

string

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

2

number

Experience points to award.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 965

cm:add_agent_experience_through_family_member(family_member family member, number points)

Adds experience points to a specified character, through a family member interface.

Parameters:

1

family_member

family memmber interface.

2

number

Experience points to award.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 971

cm:add_experience_to_unit(unit unit, number experience level to add)

Adds experience points to a supplied unit's existing experience level.

Parameters:

1

unit

unit

2

number

experience level to add

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 977

cm:add_experience_to_units_commanded_by_character(string character lookup, number level)

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

Parameters:

1

string

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

2

number

Level to increase experience of units by.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 983

cm:set_character_experience_disabled(boolean disable)

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

Parameters:

1

boolean

Disable experience. Set to false to re-enable.

Returns:

  1. nil

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

cm:set_unit_experience_disabled(boolean disable)

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

boolean

Disable experience. Set to false to re-enable.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 994

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

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

Parameters:

1

string

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

2

string

Key of unit to create, from the main_units table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 999

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

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

Parameters:

1

string

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

2

number

Logical x co-ordinate of target position.

3

number

Logical y co-ordinate of target position.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1005

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

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 - see cm:join_garrison, cm:leave_garrison and cm:attack, for example.

Parameters:

1

string

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

2

number

Logical x co-ordinate of target position.

3

number

Logical y co-ordinate of target position.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1013

cm:cancel_actions_for(string character lookup)

Immediately cancels the current actions of a specified character.

Parameters:

1

string

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

Returns:

  1. nil

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

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

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

Parameters:

1

string

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

2

number

Logical x co-ordinate of target position.

3

number

Logical y co-ordinate of target position.

Returns:

  1. boolean teleport successful

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

cm:teleport_military_force_to(military_force military force, number x, number y)

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

Military force.

2

number

Logical x co-ordinate of target position.

3

number

Logical y co-ordinate of target position.

Returns:

  1. boolean teleport successful

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1034

cm:join_garrison(string character lookup, string settlement)

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

Parameters:

1

string

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

2

string

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1042

cm:leave_garrison(string character lookup, string settlement)

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

Parameters:

1

string

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

2

string

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1048

cm:attack(
  string character lookup,
  string target character lookup,
  [boolean lay siege],
  [boolean ignore shroud]
)

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

Parameters:

1

string

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

2

string

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

3

boolean

optional, default value=false

Lay siege if the target is a garrison residence.

4

boolean

optional, default value=true

Ignores shroud restrictions. If this is set to false then the attack command is ignore if the attacker cannot see the target.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1054

cm:attack_region(string character lookup, string region key)

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

Parameters:

1

string

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

2

string

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1062

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

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

string

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

2

boolean

optional, default value=false

Lay siege if the target is a garrison residence.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1068

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

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

Parameters:

1

number

Command-queue index of the attacking character.

2

number

Command-queue index of the target character.

3

boolean

Set to true to ambush, or false to intercept.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1074

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

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

Parameters:

1

string

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

2

string

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

3

boolean

Shows the seek exchange UI.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1082

cm:replenish_action_points(string character lookup)

Replenishes the action points of a specified character.

Parameters:

1

string

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1089

cm:zero_action_points(string character lookup)

Removes all action points from a specified character.

Parameters:

1

string

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1094

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

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

Parameters:

1

string

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

2

boolean

Destroy the character and the entire military force they command.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1099

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

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

Parameters:

1

string

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

2

boolean

Destroy the character and the entire military force they command.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1105

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

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

Parameters:

1

string

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

2

number

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1111

cm:force_agent_action_success_for_human(boolean force success)

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

Parameters:

1

boolean

force success

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1117

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

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

Parameters:

1

string

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

2

string

Stance key, from the campaign_stances table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1122

cm:set_only_allow_basic_recruit_stance(boolean force basic recruitment stances)

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

Parameters:

1

boolean

force basic recruitment stances

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1128

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

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

Parameters:

1

string

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

2

string

Key of unit to remove, from the main_units table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1133

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

Sets whether the specified character can die or not.

Parameters:

1

string

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

2

boolean

is immortal

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1139

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

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

Parameters:

1

string

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

2

boolean

is unique

Returns:

  1. nil

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

cm:stop_character_convalescing(number character cqi)

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

Parameters:

1

number

character cqi

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1151

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

Modifies the loyalty of a specified character.

Parameters:

1

string

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

2

number

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1156

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

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

Parameters:

1

string

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

2

boolean

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1162

cm:remove_attack_of_opportunity_overrides(string character lookup)

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

Parameters:

1

string

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1168

cm:convert_force_to_type(military_force force, string type)

Converts a military force to a specific type.

Parameters:

1

military_force

Military force.

2

string

Military force type, from the military_force_types table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1173

cm:heal_military_force(military_force force)

Heals the supplied military force back to full health.

Parameters:

1

military_force

Military force.

Returns:

  1. nil

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

cm:set_unit_hp_to_unary_of_maximum(unit unit, number unary hp)

Sets the hit points/number of men to the given unary proportion of the maximum for that unit.

Parameters:

1

unit

Unit.

2

number

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1184

cm:set_army_trespass_disabled(boolean should disable)

Globally disable or enable army trespassing penalties.

Parameters:

1

boolean

should disable

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1190

cm:set_multi_turn_movement_enabled(boolean should enable)

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

boolean

should enable

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1195

cm:set_character_path_traversal_speed_multiplier(character character, number multiplier)

Parameters:

1

character

Character interface.

2

number

Multiplier value.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1200

cm:clear_character_path_traversal_speed_multiplier(character character)

Clears a locomotion speed multiplier of a character previously set with cm:set_character_path_traversal_speed_multiplier.

Parameters:

1

character

Character interface.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1206

cm:set_character_excluded_from_trespassing(character character, boolean excluded)

Sets a character to be excluded from trespassing calculations or not.

Parameters:

1

character

Character interface.

2

boolean

Should the character be excluded.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1211

cm:set_force_has_retreated_this_turn(military_force military force)

Sets a military force so that it behaves as if it's already retreated from battle this turn.

Parameters:

1

military_force

military force

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1217

cm:set_character_cannot_disband(character character, boolean stop disbanding)

Sets whether the provided character can disband or not.

Parameters:

1

character

Character interface.

2

boolean

Stop the desired character from disbanding.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1222

cm:suppress_immortality(number fm cqi, boolean suppress)

Suppresses or un-suppresses the immortality of the specified character. The character is specified by the command-queue index value of the related family_member interface.

Parameters:

1

number

Family member cqi.

2

boolean

Suppress immortality.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1228

Back to top

Character Armory

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,
  string armory item,
  boolean equip default,
  boolean clear conflicting items
)

Adds an armory item to a character.

Parameters:

1

character

Character to add item to.

2

string

Key for armory item to equip, from the armory_items database table.

3

boolean

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_variants database table.

4

boolean

Unequips any conflicting items when this item is equipped.

Returns:

  1. boolean item was successfully equipped

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1248

cm:remove_armory_item_from_character(character character, string armory item)

Removes an armory item from a character.

Parameters:

1

character

Character to remove item from.

2

string

Key for armory item to unequip, from the armory_items database table.

Returns:

  1. boolean item was successfully unequipped

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1257

cm:unequip_all_armory_items_from_character(character character)

Unequips all armory items equipped by the specified character.

Parameters:

1

character

Character to remove items from.

Returns:

  1. boolean any items were unequipped

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1264

cm:equip_armory_item_variant_on_character(
  character character,
  string item variant,
  boolean clear conflicting items
)

Equips a specific variant of an armory item on the specified character.

Parameters:

1

character

Character to add item to.

2

string

Variant of armory item to equip, from the armory_item_variants database table.

3

boolean

Unequips any conflicting items when this item is equipped.

Returns:

  1. boolean item was successfully equipped

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

cm:unequip_armory_item_variant_from_character(character character, string item variant)

Unequips a specific variant of an armory item from the specified character.

Parameters:

1

character

Character to add item to.

2

string

Variant of armory item to unequip, from the armory_item_variants database table.

Returns:

  1. boolean item was successfully unequipped

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1278

cm:unequip_active_item_variant_in_slot_from_character(character character, string armory slot)

Unequips any amory item variant from the specified slot of the specified character.

Parameters:

1

character

Character to add item to.

2

string

Armory slot key, from the armory_slot_types database table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1285

cm:add_armory_item_set_to_character(
  string item set,
  boolean equip default,
  boolean clear conflicting items
)

Adds all armory items in the specified armory set to the specified character.

Parameters:

1

string

Key for armory item set to equip, from the armory_item_sets database table.

2

boolean

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_variants database table.

3

boolean

Unequips any conflicting items when each item is equipped.

Returns:

  1. boolean any item was successfully equipped

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1291

cm:equip_armory_item_set_on_character(character character, string armory item set)

Equips all armory items in the specified armory set on the specified character.

Parameters:

1

character

Character to add item to.

2

string

Key for armory item set to equip, from the armory_item_sets database table.

Returns:

  1. boolean any item was successfully equipped

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

cm:is_armory_item_compatible_with_categories_on_character(character character, string armory item)

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

Character to check.

2

string

Key for armory item to check, from the armory_items database table.

Returns:

  1. boolean item is compatible

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1306

cm:is_armory_item_compatible_with_agent_subtype(character character, string armory item)

Returns whether the specified armory item is compatible with the specified character's agent subtype.

Parameters:

1

character

Character to check.

2

string

Key for armory item to check, from the armory_items database table.

Returns:

  1. boolean item is compatible

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1313

cm:can_armory_item_be_equipped_on_character(character character, string armory item)

Returns whether the specified character can equip the specified armory item.

Parameters:

1

character

Character to check.

2

string

Key for armory item to check, from the armory_items database table.

Returns:

  1. boolean item can be equipped

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1320

cm:add_armory_item_category_set_membership(character character, string category)

Add an armory set category to the specified character, allowing them to equip armory set items from that category.

Parameters:

1

character

Subject character.

2

string

Category key, from the armory_items_category_sets database table.

Returns:

  1. boolean were any items removed from the character during the category assignment

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1327

cm:remove_armory_item_category_set_membership(character character, string category)

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

character

Subject character.

2

string

Category key, from the armory_items_category_sets database table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1334

cm:clear_armory_item_category_membership(character character)

Removes all armory set categories from the specified character.

Parameters:

1

character

Subject character.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1340

cm:get_active_armory_item_variant_slot_state_for_character(character character, string item variant)

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

Character to add item to.

2

string

Variant of armory item to query, from the armory_item_variants database table.

Returns:

  1. string slot state

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1345

Back to top

Character Tinting

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(character character, boolean enable tinting)

Enables or disables tinting on the supplied character.

Parameters:

1

character

character

2

boolean

enable tinting

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1364

cm:get_tint_activity_state_for_character(character character)

Returns whether tinting is active on the supplied character.

Parameters:

1

character

character

Returns:

  1. boolean tinting enabled

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

cm:set_tint_colour_for_character(
  character character,
  string first colour key,
  number first colour intensity,
  string second colour key,
  number second colour intensity
)

Sets the tint colour for the specified character. Two colour keys from the colours database table are specified, and an intensity value for each.

Parameters:

1

character

character interface.

2

string

First colour key, from the colours database table.

3

number

Intensity of the first colour. This should be a number in the range 0-255.

4

string

Second colour key, from the colours database table.

5

number

Intensity of the second colour. This should be a number in the range 0-255.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1376

Back to top

Character Initiatives

cm:toggle_character_initiative_active(CHARACTER_INITIATIVE_INTERFACE initiative, boolean set active)

Sets a character initiative to active/inactive. A boolean value indicating whether the toggle was successful is returned.

Parameters:

1

CHARACTER_INITIATIVE_INTERFACE

initiative

2

boolean

set active

Returns:

  1. boolean toggle successful

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1397

cm:toggle_character_initiative_script_locked(
  CHARACTER_INITIATIVE_INTERFACE initiative,
  boolean script locked
)

Sets whether a character initiative is script locked. A boolean value indicating whether the toggle was successful is returned.

Parameters:

1

CHARACTER_INITIATIVE_INTERFACE

initiative

2

boolean

script locked

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1404

Back to top

Traits, Skills and Ancillaries

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

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

Parameters:

1

string

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

2

string

Trait key, from the character_traits database table.

3

number

optional, default value=1

Number of trait points to add.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1422

cm:force_add_trait_to_character_details(character_details character details, string trait key)

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

Character details interface related to the subject character.

2

string

Trait key, from the character_traits database table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1429

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

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

Parameters:

1

string

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

2

string

Trait key, from the character_traits database table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1435

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

Grant the specified ancillary to the specified character.

Parameters:

1

character

target_character

2

string

Ancillary key, from the ancillaries table.

3

boolean

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

4

boolean

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1441

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

Remove the specified ancilliary from the specified character.

Parameters:

1

character

target_character

2

string

Ancillary key, from the ancillaries table.

3

boolean

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

4

boolean

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1449

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

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

Parameters:

1

faction

target faction

2

string

Ancillary key, from the ancillaries table.

3

boolean

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1457

cm:force_remove_ancillary_from_faction(faction faction, string ancillary key)

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

Parameters:

1

faction

faction

2

string

Ancillary key, from the ancillaries table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1464

cm:reassign_ancillaries_to_character_of_same_faction(
  character source character,
  character destination character
)

Reassign all ancillaries from one character to another.

Parameters:

1

character

source character

2

character

destination character

Returns:

  1. nil

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

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

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

Parameters:

1

string

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

2

string

Skill key, from the character_skills table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1476

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

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

Parameters:

1

string

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

2

string

Skill key, from the character_skills table.

Returns:

  1. boolean skill point was removed

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1482

cm:force_reset_skills(string character lookup)

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

Parameters:

1

string

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1489

cm:remove_all_background_skills(string character lookup)

Forcibly remove all background skills for the specified character.

Parameters:

1

string

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1494

cm:set_non_scripted_traits_disabled(boolean disable)

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

Parameters:

1

boolean

disable

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1499

cm:set_non_scripted_ancillaries_disabled(boolean disable)

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

Parameters:

1

boolean

disable

Returns:

  1. nil

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

Back to top

Area Triggers

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

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

Parameters:

1

number

x display co-ordinate.

2

number

y display co-ordinate.

3

number

Radius of circle.

4

string

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

5

string

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

6

boolean

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

7

boolean

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

8

boolean

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1520

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

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

Parameters:

1

string

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

2

string

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

3

boolean

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

4

boolean

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

5

boolean

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

6

...

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

Returns:

  1. nil

Example:

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

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1532

cm:remove_area_trigger(string trigger name)

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

Parameters:

1

string

trigger name

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1554

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

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

Parameters:

1

string

Unique name for this area trigger.

2

number

Logical x co-ordinate for the hex area.

3

number

Logical y co-ordinate for the hex area.

4

number

Radius in hexes (max of 20).

5

string

optional, default value=""

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

6

string

optional, default value=""

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1559

cm:remove_hex_area_trigger(string trigger name)

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

Parameters:

1

string

trigger name

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1569

Back to top

Object Renaming

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

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

Parameters:

1

string

Faction key, from the factions table.

2

string

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1588

cm:change_custom_faction_name(string faction key, string name)

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

Parameters:

1

string

Faction key, from the factions table.

2

string

New name for the faction.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1594

cm:change_custom_settlement_name(settlement settlement, string name key)

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

Parameters:

1

settlement

Settlement interface.

2

string

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1600

cm:change_localised_settlement_name(settlement settlement, string name)

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

Parameters:

1

settlement

Settlement interface.

2

string

New name for the faction.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1606

cm:change_custom_region_name(region region, string name key)

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

Parameters:

1

region

Region interface.

2

string

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1612

cm:change_localised_region_name(region region, string name)

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

Parameters:

1

region

Region interface.

2

string

New name for the region.

Returns:

  1. nil

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

cm:change_custom_unit_name(unit unit, string name key)

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

Parameters:

1

unit

Unit interface.

2

string

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

Returns:

  1. nil

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

cm:change_localised_unit_name(unit unit, string name)

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

Parameters:

1

unit

Unit interface.

2

string

New name for the unit.

Returns:

  1. nil

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

cm:change_character_custom_name(
  character character,
  string forename,
  string surname,
  string clan name,
  string other name
)

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

character

Target character.

2

string

Forename.

3

string

Surname.

4

string

Clan name.

5

string

Other name.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1636

cm:change_character_localised_name(
  character character,
  string forename,
  string surname,
  string clan name,
  string other name
)

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

character

Target character.

2

string

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

3

string

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

4

string

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

5

string

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

Returns:

  1. 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", "", "");

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1646

cm:randomise_character_name(character character)

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

character

Target character.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1658

Back to top

Province and Faction Mechanics

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

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

ValueDescription
0minimal
1low
2normal
3high
4extortionate

Parameters:

1

string

Faction key, from the factions table.

2

number

Tax rate, from the table above.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1672

cm:exempt_region_from_tax(string region key, boolean exempt)

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

Parameters:

1

string

Region key, from the campaign_map_regions table.

2

boolean

Exempt province from tax.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1684

cm:exempt_province_from_tax_for_all_factions_and_set_default(string region key, boolean exempt)

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

Parameters:

1

string

Region key, from the campaign_map_regions table.

2

boolean

Exempt province from tax.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1690

cm:disable_rebellions_worldwide(boolean disable)

Disables or re-enables all rebellions across the map.

Parameters:

1

boolean

disable

Returns:

  1. nil

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

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

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

Parameters:

1

string

Region key, from the campaign_map_regions table.

2

number

Maximum number of units in the spawned rebellion.

3

number

Logical x co-ordinate of target position.

4

number

Logical y co-ordinate of target position.

5

boolean

Suppress the event message related to the rebellion.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1701

cm:treasury_mod(string faction key, number amount)

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

Parameters:

1

string

Faction key, from the factions table.

2

number

Treasury modification. This value must be positive.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1710

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

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

Parameters:

1

string

Region key, from the campaign_map_regions table.

2

number

Public order value.

Returns:

  1. nil

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

cm:set_public_order_disabled_for_province_for_region(string region key, boolean disable)

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

Parameters:

1

string

Region key, from the campaign_map_regions table.

2

boolean

Disable public order.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1722

cm:set_public_order_disabled_for_province_for_region_for_all_factions_and_set_default(
  string region key,
  boolean disable
)

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

Parameters:

1

string

Region key, from the campaign_map_regions table.

2

boolean

Disable public order.

Returns:

  1. nil

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

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

Adds development points to the province containing the specified region.

Parameters:

1

string

Region key, from the campaign_map_regions table.

2

number

Developments points to add.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1734

cm:add_development_points_to_horde(military_force military force, number development points)

Add development points to a horde.

Parameters:

1

military_force

military force

2

number

Developments points to add.

Returns:

  1. nil

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

cm:add_growth_points_to_region(string region key, number growth points)

Add growth points to a region

Parameters:

1

string

Region key, from the campaign_map_regions table.

2

number

Growth points to add.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1746

cm:add_growth_points_to_horde(military_force military force, number growth points)

Add growth points to a horde.

Parameters:

1

military_force

military force

2

number

Growth points to add.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1752

cm:set_imperium_level_change_disabled(boolean disable)

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

Parameters:

1

boolean

disable

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1758

cm:set_region_abandoned(string region key)

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

Parameters:

1

string

Region key, from the campaign_map_regions table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1763

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

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

Parameters:

1

string

Region key, from the campaign_map_regions table.

2

string

Faction key, from the factions table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1768

cm:create_storm_for_region(string region key, number storm strength, number duration, [string storm type])

Creates a storm of a given type in a given region.

Parameters:

1

string

Region key, from the campaign_map_regions table.

2

number

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

3

number

Duration of the storm in turns.

4

string

optional, default value=false

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1774

cm:heal_garrison(number region cqi)

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

Parameters:

1

number

Command-queue index of the target region.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1782

cm:set_liberation_options_disabled(boolean disable)

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

Parameters:

1

boolean

disable

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1787

cm:add_unit_to_faction_mercenary_pool(
  faction faction,
  string unit,
  string recruitment source,
  number count,
  number replenishment chance,
  number max units,
  number max per turn,
  string faction restriction,
  string subculture restriction,
  string tech restriction,
  boolean partial replenishment,
  string mercenary unit group
)

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

Faction whose pool the unit(s) should be added to.

2

string

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

3

string

Key of the recruitment pool that the unit will be available from, from the recruitment_sources table.

4

number

Number of units to add to the mercenary pool.

5

number

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

6

number

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

7

number

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

8

string

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

9

string

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

10

string

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

11

boolean

Allow replenishment of partial units.

12

string

The key of the mercenary unit group that contains the units you want to add, from the mercenary_unit_groups database table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1792

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

Adds one or more of a specified unit to the specified faction's mercenary pool. Unlike with cm:add_units_to_faction_mercenary_pool, the unit type must already be represented in the pool.

Parameters:

1

number

CQI of the subject faction.

2

string

Unit key, from the main_units table.

3

number

Number of units to add.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1808

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

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

Parameters:

1

region

Region within the province to which the unit(s) should be added.

2

string

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

3

number

Number of units to add to the mercenary pool.

4

number

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

5

number

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

6

number

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

7

string

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

8

string

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

9

string

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1815

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

Adds one or more of a specified unit to the specified province mercenary pool. The province is specified by a region within it. Unlike with cm:add_unit_to_province_mercenary_pool, the unit type must already be represented in the pool.

Parameters:

1

string

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

2

string

Unit key, from the main_units table.

3

number

Number of units to add.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1828

cm:change_home_region_of_faction(faction faction, region region)

Updates the home region of a faction.

Parameters:

1

faction

faction

2

region

region

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1835

cm:override_human_player_max_units(number max units)

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

number

max units

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1841

cm:add_or_remove_faction_features(faction faction, table feature list, boolean should add)

Adds or removes a feature to or from the supplied faction. Valid feature keys may be found in the faction_features database table.

Parameters:

1

faction

Faction interface.

2

table

List of features to add or remove. This should be a table of string feature keys, each from the faction_features database table.

3

boolean

Add or remove the specified feature(s).

Returns:

  1. boolean any features successfully added or removed

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1846

Back to top

Missions

cm:trigger_mission(string faction key, string mission key, boolean fire immediately)

Instructs the campaign director to attempt to trigger a mission of a particular type, based on a mission record from the database. The mission will be triggered if its conditions, defined in the cdir_events_mission_option_junctions, pass successfully. The function returns whether the mission was successfully triggered or not. Note that if the command is sent via the command queue then true will always be returned, regardless of whether the mission successfully triggers.

Parameters:

1

string

Faction key, from the factions table.

2

string

Mission key, from the missions table.

3

boolean

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

Returns:

  1. boolean mission triggered successfully

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

cm:trigger_custom_mission(string faction key, string mission key)

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

Parameters:

1

string

Faction key, from the factions table.

2

string

Mission key, from missions.txt file.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1878

cm:trigger_custom_mission_from_string(string faction key, string mission)

Triggers a custom mission from a string passed into the function. The mission string must be supplied in a custom format - see the missions.txt that commonly accompanies a campaign for examples.

Parameters:

1

string

Faction key, from the factions table.

2

string

Mission definition string.

Returns:

  1. nil

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

cm:cancel_custom_mission(string faction key, string mission key)

Cancels an active custom mission.

Parameters:

1

string

Faction key, from the factions table.

2

string

Mission key, from the missions table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1890

cm:fail_custom_mission(string faction key, string mission key)

Fails an active custom mission.

Parameters:

1

string

Faction key, from the factions table.

2

string

Mission key, from the missions table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1896

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

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

Parameters:

1

number

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

2

string

Mission key, from the missions table.

3

number

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

4

number

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

5

number

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

6

number

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

7

number

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

8

number

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1902

cm:toggle_mission_generation(boolean can generate)

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

Parameters:

1

boolean

can generate

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1915

cm:trigger_custom_incident_with_targets(
  number faction cqi,
  boolean fire immediately,
  string incident payload,
  number target faction cqi,
  number secondary faction cqi,
  number character cqi,
  number military force cqi,
  number region cqi,
  number settlement cqi
)

Attempts to trigger an incident from database records with one or more target game objects. The game object or objects to associate the mission with are specified by command-queue index. The incident will need to pass any conditions set up in the cdir_events_incidents_option_junctions database table in order to trigger.

Parameters:

1

number

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

2

boolean

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

3

string

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

4

number

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

5

number

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

6

number

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

7

number

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

8

number

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

9

number

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1920

cm:mission_is_active_for_faction(faction faction, mission key)

Checks whether the supplied faction has an active mission with the specified key.

Parameters:

1

faction

Faction.

2

mission

Mission key, from the missions database table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1933

cm:add_custom_pending_mission_from_string(
  faction recipient faction,
  faction issuing faction,
  string mission
)

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

faction

Recipient faction object.

2

faction

Issuing faction object.

3

string

Mission definition string.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1939

cm:clear_pending_missions(faction faction)

Clears any unissued pending missions for the supplied faction.

Parameters:

1

faction

Faction.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1947

Back to top

Scripted Missions

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

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

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

Parameters:

1

string

Mission key, from the missions table.

2

string

Key of the particular scripted objective associated with the mission.

3

string

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1966

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

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

Parameters:

1

string

Mission key, from the missions table.

2

string

Key of the particular scripted objective associated with the mission.

3

number

Logical x co-ordinate of the updated position.

4

number

Logical y co-ordinate of the updated position.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1973

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

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

Parameters:

1

string

Name of the faction completing the mission, from the factions database table.

2

string

Mission key, from the missions table.

3

string

Key of the particular scripted objective associated with the mission.

4

boolean

Objective was completed successfully.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1981

cm:set_scripted_mission_entity_completion_states(string mission key, string script key, table entities)

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 type SCRIPTED, where script controls the completion conditions of the mission.

Parameters:

1

string

Mission key, from the missions database table.

2

string

Key of the particular scripted objective associated with the mission.

3

table

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 as faction interface, and the second a boolean indicating whether it should be marked as completed or not on the UI.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1989

cm:remove_scripted_mission_entities(string mission key, string script key, table entities)

Remove specified entity completion states that were previously added with cm:set_scripted_mission_entity_completion_states from 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

string

Mission key, from the missions database table.

2

string

Key of the particular scripted objective associated with the mission.

3

table

Entity table. This should be a table containing one or more interface objects to remove, in the form {region, character, faction}.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 1998

Back to top

Incidents & Dilemmas

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

Instructs the campaign director to attempt to trigger a specified incident, based on record from the database. The incident will be triggered if its conditions, defined in the cdir_events_incident_option_junctions, pass successfully. The function returns whether the incident was successfully triggered or not.

Parameters:

1

string

Faction key, from the factions table.

2

string

Incident key, from the incidents table.

3

boolean

Set the incident to fire immediately.

Returns:

  1. boolean incident was triggered

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2013

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

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

Parameters:

1

string

Faction key, from the factions table.

2

string

Incident key, from the dilemmas table.

3

boolean

Set the incident to fire immediately.

4

string

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

Returns:

  1. nil

Example:

cm:trigger_custom_incident("wh_main_emp_empire", "wh_main_test_incident", true, "payload{money 1000;}");

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2021

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

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

Parameters:

1

number

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

2

string

Incident key, from the incidents table.

3

string

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

4

string

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

5

string

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

6

string

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

7

string

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

8

string

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2030

cm:toggle_incident_generation(boolean can generate)

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

Parameters:

1

boolean

can generate

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2043

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

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

Parameters:

1

string

Faction key.

2

string

Dilemma key, from the dilemma table.

3

boolean

Set the incident to fire immediately.

Returns:

  1. boolean dilemma was triggered

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2048

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

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

Parameters:

1

string

Faction key, from the factions table.

2

string

Dilemma key, from the dilemmas table.

3

string

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

4

string

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2056

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

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

Parameters:

1

string

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

2

string

Dilemma key, from the dilemmas table.

3

string

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

4

string

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2064

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

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

Parameters:

1

number

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

2

string

Dilemma key, from the dilemmas table.

3

number

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

4

number

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

5

number

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

6

number

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

7

number

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

8

number

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2072

cm:toggle_dilemma_generation(boolean can generate)

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

Parameters:

1

boolean

can generate

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2085

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

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

Parameters:

1

string

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

2

string

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

3

string

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

4

boolean

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

5

boolean

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2090

Back to top

Dilemma, Incident and Payload Builders

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(string dilemma key)

Creates and returns an empty dilemma builder. Functions provided by the returned campaign_dilemma_builder interface can be used to create a new custom dilemma from script.

Parameters:

1

string

Dilemma record key, from the dilemmas database table.

Returns:

  1. campaign_dilemma_builder dilemma builder

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2112

cm:launch_custom_dilemma_from_builder(campaign_dilemma_builder dilemma builder, faction faction)

Launches a dilemma previously constructed with cm:create_dilemma_builder for the recipient faction.

Parameters:

1

campaign_dilemma_builder

Dilemma builder interface.

2

faction

Recipient faction interface.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2118

cm:create_incident_builder(string incident key)

Creates and returns an empty incident builder. Functions provided by the returned campaign_incident_builder interface can be used to create a new custom incident from script.

Parameters:

1

string

Incident record key, from the incidents database table.

Returns:

  1. campaign_incident_builder incident builder

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2124

cm:launch_custom_incident_from_builder(campaign_incident_builder incident builder, faction faction)

Launches an incident previously constructed with cm:create_incident_builder for the recipient faction.

Parameters:

1

campaign_incident_builder

Incident builder interface.

2

faction

Recipient faction interface.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2130

cm:create_payload()
Creates and returns a new payload builder. Functions provided by the campaign_payload_builder interface which can be used to create a new payload from script, which can be applied to created dilemmas.

Returns:

  1. campaign_payload_builder custom payload

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2136

cm:apply_payload(campaign_payload_builder payload, faction faction)

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

campaign_payload_builder

Custom payload, created with cm:create_payload.

2

faction

Target faction interface.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2141

Back to top

Events and Suppression

cm:set_event_generation_enabled(boolean enable)

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

Parameters:

1

boolean

enable

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2160

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

Constructs and displays an event message.

Parameters:

1

string

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

2

string

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

3

string

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

4

string

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

5

boolean

Sets this event to be persistent instead of transient. Persistent events are saved to the event history which is accessible to the player.

6

number

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2165

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

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

Parameters:

1

string

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

2

string

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

3

string

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

4

string

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

5

number

Logical x co-ordinate of event target.

6

number

Logical y co-ordinate of event target.

7

boolean

Sets this event to be persistent instead of transient. Persistent events are saved to the event history which is accessible to the player.

8

number

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2175

cm:suppress_all_event_feed_event_types(boolean activate suppression)

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

Parameters:

1

boolean

activate suppression

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2187

cm:whitelist_event_feed_event_type(string event type)

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

Parameters:

1

string

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2194

cm:event_feed_event_type_pending(string event type)

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

Parameters:

1

string

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

Returns:

  1. boolean event is currently pending

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2200

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

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

boolean

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

2

string

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

3

string

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

4

string

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2206

Back to top

Buildings and Slots

cm:region_slot_instantly_dismantle_building(slot slot)

Instantly dismantle the building in the supplied region slot.

Parameters:

1

slot

Slot script interface.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2225

cm:region_slot_instantly_upgrade_building(slot slot, string building key)

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

Slot script interface.

2

string

Building key, from the building_levels database table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2230

cm:region_slot_instantly_repair_building(slot slot)

Instantly repair the building in the specified slot.

Parameters:

1

slot

Slot script interface.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2236

cm:foreign_slot_instantly_dismantle_building(number foreign slot cqi)

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

Parameters:

1

number

foreign slot cqi

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2241

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

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

Parameters:

1

number

Foreign slot cqi.

2

string

Building key, from the building_levels table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2246

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

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

Parameters:

1

number

Command-queue index value of the target faction.

2

number

Command-queue index value of the target region.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2252

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

Instantly set the health of a building.

Parameters:

1

string

Region key, from the campaign_map_regions table.

2

string

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

3

number

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2258

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

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

Parameters:

1

string

Building chain key, from the building_chains table.

2

string

Override building chain key, also from the building_chains table.

3

string

optional, default value=nil

Region key, from the campaign_map_regions table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2265

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

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

Parameters:

1

number

Military force command-queue index value.

2

string

Building key, from the building_levels table.

3

boolean

operation was successful

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2272

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

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

Parameters:

1

string

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

2

string

Building key, from the building_levels table.

3

boolean

operation was successful

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2279

cm:add_building_to_settlement_queue(slot target slot, string building)

Adds a building to a settlement queue, by building slot.

Parameters:

1

slot

Target slot script interface.

2

string

Building level key, from the building_levels database table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2286

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

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

Parameters:

1

number

Command-queue index value of the target faction.

2

number

Command-queue index value of the target region.

3

string

Slot set key, from the slot_sets table.

Returns:

  1. foreign_slot_manager foreign slot manager

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2293

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:

  1. building new primary building

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2301

cm:get_building_level_upgrades(string building key)

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 the building_levels database table.

Parameters:

1

string

building key

Returns:

  1. table table containing upgrade keys

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2306

Back to top

Effect Bundles

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

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

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

Parameters:

1

string

Effect bundle key, from the effect_bundles table.

2

string

Faction key, from the factions table.

3

number

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2323

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

Removes a previously-applied effect bundle from a faction.

Parameters:

1

string

Effect bundle key, from the effect_bundles table.

2

string

Faction key, from the factions table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2330

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

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

Parameters:

1

string

Effect bundle key, from the effect_bundles table.

2

number

Command-queue index of the military force.

3

number

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2336

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

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

Parameters:

1

string

Effect bundle key, from the effect_bundles table.

2

number

Command-queue index of the military force.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2343

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

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

Parameters:

1

string

Effect bundle key, from the effect_bundles table.

2

number

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

3

number

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2349

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

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

Parameters:

1

string

Effect bundle key, from the effect_bundles table.

2

number

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2356

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

Applies an effect bundle to a character.

Parameters:

1

string

Effect bundle key, from the effect_bundles table.

2

character

Target character.

3

number

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2362

cm:remove_effect_bundle_from_character(string effect bundle, character character)

Removes an effect bundle from a character.

Parameters:

1

string

Effect bundle key, from the effect_bundles table.

2

character

Target character.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2369

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

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

Parameters:

1

string

Effect bundle key, from the effect_bundles table.

2

string

Region key, from the campaign_map_regions table.

3

number

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2375

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

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

Parameters:

1

string

Effect bundle key, from the effect_bundles table.

2

string

Region key, from the campaign_map_regions table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2382

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

Applies an effect bundle to a faction province. The faction province is specified by region interface. The effect bundle will be applied to the portion of the province owned by the owner of the specified region - this can be the whole province if one faction controls it all.

Parameters:

1

string

Effect bundle key, from the effect_bundles table.

2

region

Region within the target faction province.

3

number

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2388

cm:remove_effect_bundle_from_faction_province(string effect bundle, region region)

Removes an effect bundle from a faction province. The faction province is specified by region interface. The effect bundle will be removed from the portion of the province owned by the owner of the specified region - this can be the whole province if one faction controls it all.

Parameters:

1

string

Effect bundle key, from the effect_bundles table.

2

region

Target region.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2395

Back to top

Custom Effect Bundles

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(string base effect bundle)

Creates a new custom effect bundle, using the specified effect bundle record as a base.

Parameters:

1

string

Base effect bundle key, from the effect_bundles table.

Returns:

  1. custom_effect_bundle custom effect bundle

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2414

cm:apply_custom_effect_bundle_to_region(custom_effect_bundle custom effect bundle, region region)

Applies a custom effect bundle to a region. This replaces any existing effect bundle with the same record.

Parameters:

1

custom_effect_bundle

custom effect bundle

2

region

region

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2420

cm:apply_custom_effect_bundle_to_faction(custom_effect_bundle custom effect bundle, faction faction)

Applies a custom effect bundle to a faction. This replaces any existing effect bundle with the same record.

Parameters:

1

custom_effect_bundle

custom effect bundle

2

faction

faction

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2426

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

custom effect bundle

2

character

character

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2432

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

custom effect bundle

2

military_force

military force

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2438

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

custom effect bundle

2

region

region

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2444

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

custom effect bundle

2

character

character

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2450

Back to top

Diplomacy

cm:force_diplomacy_new(
  string source faction,
  string target faction,
  number bitmask,
  boolean can offer,
  boolean can accept
)

Disables or re-enables availability of a set of diplomacy types between factions described in the faction and target specifiers. Specifiers can be all, faction:<faction_key>, subculture:<subculture_key> or culture:<culture_key>.
The diplomacy types to be allowed or disallowed are specified with a bitmask. Diplomacy types can be included in the bitmask by adding the number corresponding to the diplomacy type to the mask value. This mapping is shown here:

Diplomacy TypeMask Value
trade agreement2^0
hard military access2^1
cancel hard military access2^2
military alliance2^3
regions2^4
technology2^5
state gift2^6
payments2^7
vassal2^8
peace2^9
war2^10
join war2^11
break trade2^12
break alliance2^13
hostages2^14
marriage2^15
non aggression pact2^16
soft military access2^17
cancel soft military access2^18
defensive alliance2^19
client state2^20
form confederation2^21
break non aggression pact2^22
break soft military access2^23
break defensive alliance2^24
break vassal2^25
break client state2^26
state gift unilateral2^27
The function campaign_manager:force_diplomacy on the campaign_manager interface wraps this function, providing a more useable interface and debug output. It's recommended to call that function rather than directly calling this one.

Parameters:

1

string

Specifier that specifies one or more source factions.

2

string

Specifier that specifies one or more target factions.

3

number

Bitmask.

4

boolean

Sets whether the source faction(s) can to offer deals of this diplomacy type to the target faction(s).

5

boolean

Sets whether the target faction(s) can accept deals of this diplomacy type from the source faction(s).

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2464

cm:force_declare_war(
  string attacking faction key,
  string target faction key,
  boolean invite attacker allies,
  boolean invite defender allies
)

Forces one faction to declare war on another.

Parameters:

1

string

Faction key of the attacking faction, from the factions table.

2

string

Faction key of the target faction, from the factions table.

3

boolean

Allows factions allied with the attacker to choose whether to join.

4

boolean

Allows factions allied with the defender to choose whether to join.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2504

cm:force_make_vassal(string vassalising faction key, string vassal faction key)

Force one faction to vassalise another faction.

Parameters:

1

string

Key of the faction which will become the master, from the factions table.

2

string

Key of the faction which will become the vassal, from the factions table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2512

cm:force_alliance(string first faction key, string second faction key, boolean is military alliance)

Force two factions to become defensive or military allies.

Parameters:

1

string

Faction key of the first faction, from the factions table.

2

string

Faction key of the second faction, from the factions table.

3

boolean

Specifies whether the alliance should be a military alliance. If false is supplied then the alliance is defensive.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2518

cm:force_grant_military_access(
  string granting faction key,
  string recipient faction key,
  boolean is hard access
)

Force one faction to grant another faction military access to its territory.

Parameters:

1

string

Faction key of the granting faction, from the factions table.

2

string

Faction key of the recipient faction, from the factions table.

3

boolean

Indicates whether this should be hard military access. This concept is currently unused.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2525

cm:force_make_peace(string first faction key, string second faction key)

Forces peace between two warring factions.

Parameters:

1

string

Faction key of the first faction, from the factions table.

2

string

Faction key of the second faction, from the factions table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2532

cm:force_rebellion_with_faction(
  region region,
  string faction key,
  number max units,
  boolean full strength,
  [boolean suppress public order penalty]
)

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

region

Interface of the region in which to spawn rebellion force.

2

string

Faction key of the rebelling faction, from the factions database table.

3

number

Maximum number of units to spawn.

4

boolean

Spawn at full strength or not.

5

boolean

optional, default value=false

Set this argument to true for the rebellion to not affect public order in the target region.

Returns:

  1. military_force spawned military force

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2538

cm:force_confederation(string proposing faction key, string target faction key)

Forces a proposing faction to subsume a target faction into its confederation.

Parameters:

1

string

Faction key of the proposing faction, from the factions table.

2

string

Faction key of the target faction, from the factions table. This faction will be subsumed into the confederation.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2548

cm:force_make_trade_agreement(string first faction key, string second faction key)

Forces a trade agreement between two specified factions. If no agreement is possible then nothing will happen.

Parameters:

1

string

Faction key of the first faction, from the factions table.

2

string

Faction key of the second faction, from the factions table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2554

cm:make_diplomacy_available(string first faction key, string second faction key)

Makes diplomacy available between two factions, as if they had discovered each other on the campaign map.

Parameters:

1

string

Faction key of the first faction, from the factions table.

2

string

Faction key of the second faction, from the factions table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2560

cm:faction_offers_peace_to_other_faction(string proposing faction key, string target faction key)

Compels one faction to offer peace to another faction that it's at war with. The target faction may decline.

Parameters:

1

string

Faction key of the first faction, from the factions table.

2

string

Faction key of the second faction, from the factions table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2566

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

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

Parameters:

1

string

First faction key.

2

string

Second faction key.

3

number

Bonus value (-6 to +6).

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2572

Back to top

Restrictions

cm:add_event_restricted_unit_record(string unit key, [string tooltip key])

Adds a restriction preventing a specified unit from being a recruitment option for any faction.
This setting is saved into the campaign save file when the game is saved, and automatically re-established when the campaign is reloaded.

Parameters:

1

string

Unit key, from the main_units table.

2

string

optional, default value=nil] string tooltip key, Key of localised text in full [table]_[field]_[key

Key of localised text in full [table]_[field]_[key] format to show as a tooltip on the restricted unit icon. This can be omitted.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2589

cm:remove_event_restricted_unit_record(string unit key)

Removes a restriction previously added with cm:add_event_restricted_unit_record.

Parameters:

1

string

Unit key, from the main_units table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2596

cm:add_event_restricted_unit_record_for_faction(string unit key, string faction key, [string tooltip key])

Adds a restriction preventing a specified unit from being a recruitment option for a specified faction.
This setting is saved into the campaign save file when the game is saved, and automatically re-established when the campaign is reloaded.

Parameters:

1

string

Unit key, from the main_units table.

2

string

Faction key, from the factions table.

3

string

optional, default value=nil] string tooltip key, Key of localised text in full [table]_[field]_[key

Key of localised text in full [table]_[field]_[key] format to show as a tooltip on the restricted unit icon. This can be omitted.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2601

cm:remove_event_restricted_unit_record_for_faction(string unit key, string faction key)

Removes a restriction previously added with cm:add_event_restricted_unit_record_for_faction.

Parameters:

1

string

Unit key, from the main_units table.

2

string

Faction key, from the factions table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2609

cm:add_event_restricted_building_record(string building key, [string tooltip key])

Adds a restriction preventing a specified building from being a construction option for any faction.
This setting is saved into the campaign save file when the game is saved, and automatically re-established when the campaign is reloaded.

Parameters:

1

string

Building key, from the building_levels table.

2

string

optional, default value=nil] string tooltip key, Key of localised text in full [table]_[field]_[key

Key of localised text in full [table]_[field]_[key] format to show as a tooltip on the restricted building icon. This can be omitted.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2615

cm:remove_event_restricted_building_record(string building key)

Removes a restriction previously added with cm:add_event_restricted_building_record.

Parameters:

1

string

Building key, from the building_levels table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2622

cm:add_event_restricted_building_record_for_faction(
  string building key,
  string faction key,
  [string tooltip key]
)

Adds a restriction preventing a specified building from being a construction option for a specified faction.
This setting is saved into the campaign save file when the game is saved, and automatically re-established when the campaign is reloaded.

Parameters:

1

string

Building key, from the building_levels table.

2

string

Faction key, from the factions table.

3

string

optional, default value=nil] string tooltip key, Key of localised text in full [table]_[field]_[key

Key of localised text in full [table]_[field]_[key] format to show as a tooltip on the restricted building icon. This can be omitted.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2627

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

Removes a restriction previously added with cm:add_event_restricted_building_record_for_faction.

Parameters:

1

string

Building key, from the building_levels table.

2

string

Faction key, from the factions table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2635

cm:lock_technology(string faction key, string technology key)

Lock a specified technology and all technologies that are children of it, for a specified faction.
This setting is saved into the campaign save file when the game is saved, and automatically re-established when the campaign is reloaded.

Parameters:

1

string

Faction key, from the factions table.

2

string

Technology key, from the technologies table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2641

cm:lock_one_technology_node(string faction key, string technology key)

Lock one technology node, without locking any of its children.

Parameters:

1

string

Faction key, from the factions database table.

2

string

Technology key, from the technologies database table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2648

cm:unlock_technology(string faction key, string technology key)

Removes a lock previously placed with cm:lock_technology.

Parameters:

1

string

Faction key, from the factions table.

2

string

Technology key, from the technologies table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2654

cm:update_technology_unlock_progress_values(
  string faction key,
  string technology key,
  table progress values
)

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 the technology_script_lock_reasons database 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. Use cm:unlock_technology to unlock the technology at this time.

Parameters:

1

string

Key of the faction owning the technology, from the factions database table.

2

string

Key of the technology, from the technologies database table.

3

table

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:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2660

cm:building_level_unlocks_technology_for_faction(faction faction, string building key)

Returns whether the specified building level unlocks any technologies for the specified faction.

Parameters:

1

faction

Faction interface.

2

string

Building level key, from the building_levels database table.

Returns:

  1. boolean building level unlocks technology/technologies

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2670

cm:disable_movement_for_character(string character lookup)

Prevents the specified character from moving, regardless of where the move order comes from, until movement is subsequently re-enabled with cm:enable_movement_for_faction or cm:enable_movement_for_character.
This setting is saved into the campaign save file when the game is saved, and automatically re-established when the campaign is reloaded.

Parameters:

1

string

Character lookup string - see Character Lookups for more information.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2677

cm:disable_movement_for_faction(string faction key)

Prevents all characters in the specified faction from moving, regardless of where the move order comes from, until movement is subsequently re-enabled with cm:enable_movement_for_faction or cm:enable_movement_for_character. Note that characters created in the faction after this restriction is applied will not have this restriction applied and will be able to move.
This setting is saved into the campaign save file when the game is saved, and automatically re-established when the campaign is reloaded.

Parameters:

1

string

Faction key, from the factions table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2683

cm:enable_movement_for_character(string character lookup)

Re-enables movement for a specified character after it has been disabled with cm:disable_movement_for_character or cm:disable_movement_for_faction.

Parameters:

1

string

Character lookup string - see Character Lookups for more information.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2689

cm:enable_movement_for_faction(string faction key)

Re-enables movement for every character in the specified faction after it has been disabled with cm:disable_movement_for_character or cm:disable_movement_for_faction.

Parameters:

1

string

Faction key, from the factions table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2694

cm:disable_pathfinding_restriction(number id)

Disables a pathfinding restriction layer. These are layers that can be built into the campaign map data that prevent the player from being able to move into an area on the map. By calling this function to lift a restriction, the player will be able to pathfind into the new area.
Note that the enable_scripted_pathfinding_restrictions campaign variable must be set for restrictions to work - create an entry for this variable and the campaign in the campaigns_campaign_variables_junctions table.

Parameters:

1

number

Pathfinding restriction layer id to un-restrict. Layers are numbered sequentially - lifting the restriction on one layer will also lift it on all layers with a lower numerical id.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2699

Back to top

Pooled Resources

cm:faction_add_pooled_resource(string faction key, string resource key, string factor key, number amount)

Add the specified amount to the specified resource pool (type of resource), as the specified factor (type of change). The supplied value will be clamped to pool and factor bounds.

Parameters:

1

string

Faction key, from the factions table.

2

string

Pooled resource key, from the pooled_resources table.

3

string

Change factor key, from the pooled_resource_factors table.

4

number

Amount of resource to add. This value can be negative.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2718

cm:add_regular_pooled_resource_transaction(
  interface entity interface,
  string resource cost key,
  number turns
)

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_costs table.

Parameters:

1

interface

Interface of entity to apply the pooled resource transaction to e.g. character, faction.

2

string

Key of the resource cost record to apply, from the resource_costs database table.

3

number

Number of turns to apply the transaction for. If 0 is supplied, the transaction is applied indefinitely.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2726

cm:remove_regular_pooled_resource_transaction(interface entity interface, string resource cost key)

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

interface

Interface of entity to remove the pooled resource transaction from e.g. province, military_force.

2

string

Key of the resource cost record to remove, from the resource_costs database table. If a blank string is supplied then all resource costs are removed.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2733

cm:pooled_resource_transaction(pooled_resource_manager resource manager, string resource cost key)

Apply a transaction to a pooled resource manager. A record from the resource_costs database table is specified, which determines the factors and amounts of pooled resources to modify.

Parameters:

1

pooled_resource_manager

Resource manager interface.

2

string

Key of the resource cost record to apply, from the resource_costs database table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2739

cm:pooled_resource_factor_transaction(
  pooled_resource_manager resource manager,
  string resource factor key,
  number amount
)

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

pooled_resource_manager

Resource manager interface.

2

string

Key of the resource factor to change, from the pooled_resource_factors database table.

3

number

Change amount. This may be negative.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2745

cm:apply_regular_reset_income(pooled_resource_manager resource manager)

Apply regular pooled resoure income and expenditure on provided pooled resource manager.

Parameters:

1

pooled_resource_manager

Resource manager interface.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2752

Back to top

Winds of Magic

cm:force_winds_of_magic_change(string area key, string strength key)

Forces a change in the winds of magic for a given area.

Parameters:

1

string

Winds of Magic area key, from the campaign_map_winds_of_magic_area database table.

2

string

Winds of Magic strength key, from the campaign_map_winds_of_magic_strengths database table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2766

Back to top

Rituals

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(string performing faction key, string target faction key, string ritual key)

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

Parameters:

1

string

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

2

string

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

3

string

Ritual key, from the rituals table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2784

cm:create_new_ritual_setup(faction performing_faction, string ritual key)

Creates and returns a new modify ritual setup interface, based on an existing ritual.

Parameters:

1

faction

Faction to perform the ritual.

2

string

Ritual key, from the rituals table.

Returns:

  1. modify_ritual_setup modify ritual setup interface

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2791

cm:perform_ritual_with_setup(modify_ritual_setup 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

modify_ritual_setup

Ritual setup to use. This may be either a mutable modify_ritual_setup or immutable ritual_setup object.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2798

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

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

Parameters:

1

string

Ritual chain key, from the campaign_group_ritual_chains table.

2

number

Stage number.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2803

cm:lock_ritual(faction faction, string ritual key)

Lock a ritual for a faction.

Parameters:

1

faction

Target faction interface.

2

string

Ritual key, from the rituals table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2809

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

Unlock a ritual for a faction.

Parameters:

1

faction

Target faction interface.

2

string

Ritual key, from the rituals table.

3

number

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2815

cm:lock_ritual_chain(faction faction, string ritual_chain_key)

Lock a ritual chain for a faction.

Parameters:

1

faction

Target faction interface.

2

string

Ritual chain key, from the ritual_chains table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2822

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

Unlock a ritual chain for a faction.

Parameters:

1

faction

Target faction interface.

2

string

Ritual Chain key, from the ritual_chains table.

3

number

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2828

cm:lock_rituals_in_category(faction faction, string ritual_category_key)

Lock all rituals in a category for a faction.

Parameters:

1

faction

Target faction interface.

2

string

Ritual category key, from the ritual_categories table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2835

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

Unlock rituals in a category for a faction.

Parameters:

1

faction

Target faction interface.

2

string

Ritual category key, from the ritual_categories table.

3

number

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2841

cm:apply_active_ritual(faction faction, active_ritual ritual)

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

Parameters:

1

faction

Target faction interface.

2

active_ritual

Target ritual interface.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2848

cm:apply_active_rituals(faction faction)

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

Parameters:

1

faction

Target faction.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2855

Back to top

Plagues

cm:spawn_plague_at_settlement(settlement settlement, string plague key)

Spawn a plague at a settlement.

Parameters:

1

settlement

Target settlement.

2

string

Plague key, from the plagues table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2873

cm:spawn_plague_at_region(region region, string plague key)

Spawn a plague in a region.

Parameters:

1

region

Target region.

2

string

Plague key, from the plagues table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2879

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

Spawn a plague at a military force.

Parameters:

1

military_force

Target military force.

2

string

Plague key, from the plagues table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2885

cm:set_military_force_plague(military_force military force, string plague key)

Sets the plague on a military force.

Parameters:

1

military_force

Target military force.

2

string

Plague key, from the plagues table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2891

Back to top

Cooking

cm:cook_recipe(faction faction, string recipe)

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

Parameters:

1

faction

Faction interface.

2

string

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

Returns:

  1. boolean attempt was successful

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2909

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

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

Parameters:

1

faction

Faction interface.

2

string

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

3

table

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

4

table

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

Returns:

  1. boolean attempt was successful

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2916

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

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

Parameters:

1

faction

Faction interface.

2

string

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

3

boolean

Apply the recipe cost.

Returns:

  1. boolean attempt was successful

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2925

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

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

Parameters:

1

faction

Faction interface.

2

string

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

3

table

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

4

table

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

5

boolean

Apply the recipe cost.

Returns:

  1. boolean attempt was successful

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2933

cm:unlock_cooking_ingredient(faction faction, string ingredient)

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

Parameters:

1

faction

Faction interface.

2

string

Ingredient key, from the cooking_ingredients database table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2943

cm:unlock_cooking_recipe(faction faction, string recipe)

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

Parameters:

1

faction

Faction interface.

2

string

Recipe key, from the cooking_recipes database table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2949

cm:clear_active_cooking_recipe(faction faction)

Clears the active recipe for the specified faction.

Parameters:

1

faction

Faction interface.

Returns:

  1. boolean recipe was cleared

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2955

cm:set_faction_max_primary_cooking_ingredients(faction faction, number max ingredients)

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

Parameters:

1

faction

Faction interface.

2

number

Maximum number of ingredients.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2961

cm:set_faction_max_secondary_cooking_ingredients(faction faction, number max ingredients)

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

Parameters:

1

faction

Faction interface.

2

number

Maximum number of ingredients.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2967

Back to top

Caravans

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(faction faction, caravan_recruitment_item caravan recruitment item)

Recruits the specified caravan recruitment item into the specified faction. If successful, a caravan script interface is returned.

Parameters:

1

faction

Faction interface.

2

caravan_recruitment_item

Caravan recruitment item interface.

Returns:

  1. caravan recruited caravan, or null if no caravan recruited.

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2986

cm:start_caravan(faction faction, family_member family member, number cargo, route_node start node)

Start a character on a new caravan journey. If successful, the caravan script interface is returned.

Parameters:

1

faction

Faction interface.

2

family_member

Family member interface of caravan master character.

3

number

Cargo value.

4

route_node

Starting node of journey.

Returns:

  1. caravan the caravan starting the journey, or null if no caravan could embark.

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 2993

cm:set_caravan_cargo(caravan caravan, number cargo)

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

Caravan script interface.

2

number

Cargo value.

Returns:

  1. number cargo value set

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3002

cm:set_caravan_path(caravan caravan, route_path path destination)

Set the path of a caravan. A boolean value indicating whether the path was successfully set is returned.

Parameters:

1

caravan

caravan

2

route_path

path destination

Returns:

  1. boolean caravan path successfully set

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3009

cm:set_caravan_auto_path(caravan caravan, route_position target)

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

caravan

2

route_position

target

Returns:

  1. boolean caravan path successfully set

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3016

cm:clear_caravan_path(caravan caravan)

Clears a caravan's current path. A boolean value indicating whether the path was successfully cleared is returned.

Parameters:

1

caravan

caravan

Returns:

  1. boolean caravan path successfully cleared

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3023

cm:move_caravan(caravan caravan)

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

caravan

Returns:

  1. boolean caravan successfully moved

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3029

cm:set_region_caravan_banditry(region_data region, number banditry value)

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_variables database table (or the campaigns_campaign_variables_junctions override table).

Parameters:

1

region_data

region

2

number

banditry value

Returns:

  1. number set banditry value

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3035

cm:set_multi_region_caravan_banditry(table regions, number banditry value)

Set the banditry value for multiple regions, supplied as region_data objects in a lua table.

Parameters:

1

table

Table of region_data objects.

2

number

banditry value

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3042

Back to top

Teleportation Networks

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(string node key, [string template key])

Opens a specific teleportation node. The template key may be omitted if one is already defined in the teleportation_network_nodes record in the database, otherwise it's required.

Parameters:

1

string

Node record key, from the teleportation_network_nodes database table.

2

string

optional, default value=nil

Teleportation network node template key, from the teleportation_node_templates database table. This only needs to be provided if the node record specified in the first argument does not provide a template.

Returns:

  1. boolean network node opened successfully

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3058

cm:teleportation_network_close_node(string node key)

Closes a specified teleportation node.

Parameters:

1

string

Node record key, from the teleportation_network_nodes database table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3065

cm:teleportation_network_open_random_nodes(string network key, string template key, number nodes to open)

Opens random nodes in a given teleportation network with the specified template type. The number of nodes opened is returned.

Parameters:

1

string

Node network key, from the teleportation_networks database table.

2

string

Node template key of nodes to open, from the teleportation_node_templates database table.

3

number

Target number of nodes to open.

Returns:

  1. number number of nodes opened

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3070

cm:teleportation_network_close_random_nodes(
  string network key,
  string template key,
  number nodes to close
)

Closes random nodes in a teleportation network with a specific template type. The number of nodes closed is returned.

Parameters:

1

string

Node network key, from the teleportation_networks database table.

2

string

Node template key of nodes to open, from the teleportation_node_templates database table.

3

number

Target number of nodes to close.

Returns:

  1. number number of nodes closed

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3078

cm:teleportation_network_close_all_nodes(string network key, [string template key])

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

string

Node network key, from the teleportation_networks database table.

2

string

optional, default value=nil

Node template key of nodes to close, from the teleportation_node_templates database table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3086

cm:teleportation_network_set_effect_level_modifier(string network key, number modifier)

Set an effect level modifier to be applied to the nodes of a given teleportation network.

Parameters:

1

string

Node network key, from the teleportation_networks database table.

2

number

Modifier value.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3092

Back to top

Misc Racial Mechanics

The functions described in this section affect racial mechanics that are generally specific to one or only a few races in the game. Avoid calling them for factions that aren't party to the racial mechanic in question.

cm:set_next_winds_of_magic_compass_selection_cooldown(faction faction, number turns)

Sets the cooldown in turns before the compass heading may be changed for the specified faction.

Parameters:

1

faction

Faction interface.

2

number

Number of turns before the faction may alter the compass direction.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3110

cm:modify_faction_slaves_in_a_faction(string faction key, number change)

Modify the number of faction slaves in the specified faction. The change can be positive or negative. This function will only have an affect if the target faction makes use of the slaves mechanic.

Parameters:

1

string

Faction key, from the factions table.

2

number

Value to modify slaves by.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3116

cm:modify_faction_slaves_in_a_faction_province(string region key, number change)

Modify the number of faction slaves in the province containing a specified region. The change can be positive or negative. This function will only have an affect if the target faction makes use of the slaves mechanic.

Parameters:

1

string

Region key, from the campaign_map_regions table.

2

number

Value to modify slaves by.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3122

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

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

Parameters:

1

string

Faction key, from the factions table.

2

string

Food factor key, from the food_factors table.

3

number

Multiplier.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3128

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

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

Parameters:

1

string

Faction key, from the factions table.

2

string

Food factor key, from the food_factors table.

3

number

Modifier.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3135

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

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

Parameters:

1

string

Faction key, from the factions table.

2

string

Food factor key, from the food_factors table.

3

number

Modifier.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3142

cm:faction_purchase_unit_effect(faction faction, unit unit, unit_purchasable_effect 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

faction

2

unit

unit

3

unit_purchasable_effect

purchasable effect

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3150

cm:faction_unpurchase_unit_effect(unit unit, unit_purchasable_effect 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

unit

2

unit_purchasable_effect

purchasable effect

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3157

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

Locks or unlocks the purchasable unit effect faction-wide, with an optional lock reason record.

Parameters:

1

faction

Faction interface.

2

string

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

3

string

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

4

boolean

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3163

cm:faction_imprison_character(faction imprisoning faction, character imprisoned character)

Puts the supplied character into the supplied faction's prison.

Parameters:

1

faction

imprisoning faction

2

character

imprisoned character

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3171

cm:faction_perform_action_on_prisoner(faction faction, family_member character, string action)

Performs an action on a character within the faction's prison.

Parameters:

1

faction

Imprisoning faction.

2

family_member

Family member interface related to the imprisoned character.

3

string

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

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3177

Back to top

Pending Battle Modifications

cm:add_custom_battlefield(
  string id,
  number x,
  number y,
  number radius,
  boolean dump campaign,
  string loading screen override,
  string script override,
  string whole battle override,
  number human alliance,
  boolean launch immediately,
  boolean is land battle,
  boolean force autoresolve result
)

Adds a record which modifies or completely overrides a 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 the campaign_manager intercepts 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 the Custom Battlefields section.

Parameters:

1

string

Id for this custom battle record. This may be used to later remove this override with cm:remove_custom_battlefield.

2

number

X logical co-ordinate of anchor position.

3

number

Y logical co-ordinate of anchor position.

4

number

Radius around anchor position. If a battle is launched within this radius of the anchor position and it involves the local player, then the battle is modified/overridden.

5

boolean

If set to true, the battle makes no attempt to load back into this campaign after completion.

6

string

Key of a custom loading screen to use, from the custom_loading_screens table. A blank string may be supplied to not override the loading screen. This is ignored if the entire battle is overriden with a battle xml, as that may specify a loading screen override.

7

string

Path to a script file to load with the battle, from the working data folder. A blank string may be supplied to not override the loading screen. This is ignored if the entire battle is overriden with a battle xml, as that may specify a script override.

8

string

Path to an battle xml file which overrides the whole battle.

9

number

Sets the index of the human alliance, 0 or 1, if setting a battle xml to override the whole battle. If not setting a battle xml this number is ignored.

10

boolean

Launch the battle immediately without saving the campaign first.

11

boolean

Sets whether the following battle is a land battle. This is only required if when launching the battle immediately.

12

boolean

If set to true, this forces the application of the autoresolver to the battle result after the battle, regardless of what happened in the battle itself. This is of most use for faking a battle result of an xml battle, which would otherwise return with no result.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3194

cm:remove_custom_battlefield(string id)

Removes a custom battle override previously set with cm:add_custom_battlefield.
Note that the campaign_manager intercepts 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 the Custom Battlefields section.

Parameters:

1

string

id

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3211

cm:clear_custom_battlefields()
Removes all custom battle overrides previously set with cm:add_custom_battlefield.
Note that the campaign_manager intercepts 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 the Custom Battlefields section.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3217

cm:win_next_autoresolve_battle(string faction key)

The specified faction will win the next autoresolve battle.

Parameters:

1

string

Faction key, from the factions table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3222

cm:modify_next_autoresolve_battle(
  number attacker win chance,
  number defender win chance,
  number attacker losses modifier,
  number defender losses modifier,
  boolean kill loser
)

Modifies the result of the next autoresolved battle.

Parameters:

1

number

Attacker win chance as a unary (0-1) value.

2

number

Defender win chance as a unary (0-1) value.

3

number

Multiplier for losses sustained by the attacker.

4

number

Multiplier for losses sustained by the defender.

5

boolean

Forces the loser of the battle to be wiped out if set to true.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3227

cm:skip_winds_of_magic_gambler(boolean should skip)

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

Parameters:

1

boolean

should skip

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3236

cm:override_attacker_win_chance_prediction(number chance)

Set the attackers predicted win chance percentage for the next battle, affecting the balance of power shown on the pre-battle screen. This will not change the result.
This function will only work if called while the pending battle is being set up.

Parameters:

1

number

Chance as a percentage, so a value of 50 would display a 50/50 attacker/defender balance.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3241

cm:pending_battle_add_scripted_tile_upgrade_tag(string tile upgrade key)

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

Parameters:

1

string

tile upgrade key

Returns:

  1. boolean upgrade was successful

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3247

cm:pending_battle_remove_scripted_tile_upgrade_tags(string tile upgrade key)

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

Parameters:

1

string

tile upgrade key

Returns:

  1. boolean upgrade was successful

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3254

cm:set_battle_lighting_env_override(string file_name)
Override the battle environment of upcoming battles. This needs to be cleared by calling it without any parameters.

Parameters:

1

string

The file path of the battle environment file. E.g. "weather/battle/wh_day_clear_02.environment_group"

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3260

cm:update_pending_battle()
Rebuild pending battle setup and autoresolve results. This should be called after any model modification, when processing the PendingBattle event.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3265

cm:set_prebattle_display_configuration_override(
  number distance,
  number height,
  number bearing,
  number scale,
  number scale
)

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

number

Camera distance.

2

number

Camera height.

3

number

Bearing from camera to target in radians.

4

number

Unary scale of army leaders.

5

number

Separation of army leaders.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3269

cm:set_prebattle_display_configuration_camera_type_override(string camera type)

Set an override for the prebattle display camera configuration type. Valid values are "character", "settlement" and "tunnel".

Parameters:

1

string

camera type

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3278

cm:clear_prebattle_display_configuration_override()
Clears any prebattle display configuration overrides previously set with cm:set_prebattle_display_configuration_override or cm:set_prebattle_display_configuration_camera_type_override.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3283

cm:set_loading_screen_id(string loading screen id)

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

string

loading screen id

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3287

Back to top

Character Observation Options

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_faction

  • observation_options_for_allies

  • observation_options_for_enemies

  • observation_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(
  faction subject faction,
  observation_options observation options
)

Sets character observation options for a specific faction. The observation_options may be retrieved by calling observation_options_for_faction on a world interface, and calling functions on it to customise view options before passing it back to this function.

Parameters:

1

faction

subject faction

2

observation_options

observation options

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3311

cm:set_character_observation_options_for_allies(observation_options observation options)

Sets character observation options for all allies. The observation_options may be retrieved by calling observation_options_for_allies on a world interface, and calling functions on it to customise view options before passing it back to this function.

Parameters:

1

observation_options

observation options

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3317

cm:set_character_observation_options_for_enemies(observation_options observation options)

Sets character observation options for all enemies. The observation_options may be retrieved by calling observation_options_for_enemies on a world interface, and calling functions on it to customise view options before passing it back to this function.

Parameters:

1

observation_options

observation options

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3322

cm:set_character_observation_options_for_neutrals(observation_options observation options)

Sets character observation options for all neutral factions. The observation_options may be retrieved by calling observation_options_for_neutrals on a world interface, and calling functions on it to customise view options before passing it back to this function.

Parameters:

1

observation_options

observation options

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3327

Back to top

Achievements

cm:award_achievement(string achievement key)

Awards an achievement to the local player.

Parameters:

1

string

Achievement key, from the achievements database table.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3342

Back to top

War Co-ordination Interface

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:

  1. war_coordination war co-ordination interface

defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3359

Back to top

AI

The functions in this section relate to campaign AI. Some functions allow blocking or promotion of strategic stances, which is a driver of how much an AI faction is predisposed to like another faction. Strategic stances may be specified by one of the following strings:

  • CAI_STRATEGIC_STANCE_BEST_FRIENDS

  • CAI_STRATEGIC_STANCE_VERY_FRIENDLY

  • CAI_STRATEGIC_STANCE_FRIENDLY

  • CAI_STRATEGIC_STANCE_NEUTRAL

  • CAI_STRATEGIC_STANCE_UNFRIENDLY

  • CAI_STRATEGIC_STANCE_VERY_UNFRIENDLY

  • CAI_STRATEGIC_STANCE_BITTER_ENEMIES
    • Stance by string
    CAI_STRATEGIC_STANCE_BEST_FRIENDS

    Strategic stances are different to, but loosely correlated with, the attitude score that is shown on the diplomacy screen. Generally speaking, diplomatic events (e.g. gifts, trespassing) lead to changes in attitude, which leads to changes in strategic stance, which leads to changes in behaviour. By setting two hostile factions to be best friends they will start being generally nicer to one another while still appearing to be hostile (although their attitude will likely improve over time due to positive events).

    cm:set_base_strategic_threat_score(faction faction interface, number threat score)

    Set the base strategic threat score for a faction. This corresponds to score levels seen in the faction_strategic_threat_levels database table.

    Parameters:

    1

    faction

    faction interface

    2

    number

    threat score

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3387

    cm:force_change_cai_faction_personality(string faction key, string personality key)

    Force the specified faction to adopt the specified AI personality.

    Parameters:

    1

    string

    Faction key, from the factions table.

    2

    string

    Personality key, from the cai_personalities table.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3393

    cm:cai_strategic_stance_manager_block_all_stances_but_that_specified_towards_target_faction(
          string faction key,
      string     target faction key,
      string     strategic stance key
    )

    Sets one faction's stance towards another to the supplied strategic stance.

    Parameters:

    1

    string

    Faction key, from the factions table.

    2

    string

    Target faction key, from the factions table.

    3

    string

    Strategic stance key - see the list at the top of this section.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3399

    cm:cai_strategic_stance_manager_promote_specified_stance_towards_target_faction(
          string faction key,
      string     target faction key,
      string     strategic stance key
    )

    Makes it much more likely that one faction's stance towards another will be the supplied strategic stance.

    Parameters:

    1

    string

    Faction key, from the factions table.

    2

    string

    Target faction key, from the factions table.

    3

    string

    Strategic stance key - see the list at the top of this section.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3406

    cm:cai_force_personality_change(string faction key)

    Forces the specified faction to pick a new AI personality from their available pool. "All" may be supplied in place of a faction key to force all factions to change personalities.

    Parameters:

    1

    string

    Faction key, from the factions table, or "all".

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3413

    cm:cai_force_personality_change_with_override_round_number(string faction key, number round number)

    Within the ai personality assignment system it is possible to set up weightings between rounds and personalities, allowing for certain personalities to be more or less likely to be chosen depending on the turn number (so the AI changes behaviour over time). This command forces the specified faction to pick a new AI personality from their available pool, based on the supplied round number rather than the actual round number. "All" may be supplied in place of a faction key to force all factions to change personalities in this way.

    Parameters:

    1

    string

    Faction key, from the factions table, or "all".

    2

    number

    Override for turn/round number.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3418

    cm:cai_strategic_stance_manager_force_stance_update_between_factions(
          string faction key,
      string     target faction key
    )

    Forces a stance update from one faction to another faction. The AI picks an appropriate new strategic stance.

    Parameters:

    1

    string

    Faction key, from the factions table.

    2

    string

    Target faction key, from the factions table.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3424

    cm:cai_strategic_stance_manager_set_stance_promotion_between_factions_for_a_given_stance(
          string faction key,
      string     target faction key,
      string     strategic stance key,
      number     start round,
      number     start level,
      number     end round,
      number     end level
    )

    Sets up a process which promotes a particular strategic stance from one faction to a target faction over a number of turns.

    Parameters:

    1

    string

    Faction key, from the factions table.

    2

    string

    Target faction key, from the factions table.

    3

    string

    Strategic stance key - see the list at the top of this section.

    4

    number

    Starting round number.

    5

    number

    Starting stance level. This is a numerical indicator of how likely this stance is to be chosen.

    6

    number

    End round number.

    7

    number

    End stance level. This is a numerical indicator of how likely this stance is to be chosen.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3430

    cm:cai_strategic_stance_manager_clear_all_promotions_between_factions(
          string faction key,
      string     target faction key
    )

    Clears any existing scripted stance promotions from one faction to a target faction.

    Parameters:

    1

    string

    Faction key, from the factions table.

    2

    string

    Target faction key, from the factions table.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3441

    cm:cai_strategic_stance_manager_set_stance_blocking_between_factions_for_a_given_stance(
          string faction key,
      string     target faction key,
      string     strategic stance key,
      number     round number
    )

    Blocks a specific strategic stance from one faction to another faction until a specified round number.

    Parameters:

    1

    string

    Faction key, from the factions table.

    2

    string

    Target faction key, from the factions table.

    3

    string

    Strategic stance key - see the list at the top of this section.

    4

    number

    Final round number (inclusive) of blocking behaviour.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3447

    cm:cai_strategic_stance_manager_clear_all_blocking_between_factions(
          string faction key,
      string     target faction key
    )

    Clears any existing scripted stance promotions between one faction and a target.

    Parameters:

    1

    string

    Faction key, from the factions table.

    2

    string

    Target faction key, from the factions table.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3455

    cm:cai_disable_movement_for_character(string character lookup)

    Prevents the AI from being able to move a character. Other sources of character movement (e.g. the script or the player) will work as normal.

    Parameters:

    1

    string

    Character lookup string - see Character Lookups for more information.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3461

    cm:cai_enable_movement_for_character(string character lookup)

    Allows the AI to move a character again after it was previously blocked with cm:cai_disable_movement_for_character.

    Parameters:

    1

    string

    Character lookup string - see Character Lookups for more information.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3466

    cm:cai_disable_movement_for_faction(string faction key)

    Prevents the AI from being able to move any characters in a faction. Other sources of character movement (e.g. the script or the player) will work as normal.

    Parameters:

    1

    string

    Faction key, from the factions table.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3471

    cm:cai_enable_movement_for_faction(string faction key)

    Allows the AI to move characters in a faction again after it was previously blocked with cm:cai_disable_movement_for_faction.

    Parameters:

    1

    string

    Faction key, from the factions table.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3476

    cm:cai_disable_command_assignment_for_character(string character lookup)

    Prevents the AI from assigning the specified character to a position of command.

    Parameters:

    1

    string

    Character lookup string - see Character Lookups for more information.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3481

    cm:cai_enable_command_assignment_for_character(string character lookup)

    Allows the AI to assigning the specified character to a position of command again after it was previously blocked with cm:cai_disable_command_assignment_for_character.

    Parameters:

    1

    string

    Character lookup string - see Character Lookups for more information.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3486

    cm:cai_add_diplomatic_event(string originating faction, string target faction, string diplomatic action)

    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

    string

    Key of the faction the diplomatic event is originating from, from the factions database table.

    2

    string

    Key of the faction the diplomatic event is targeting, from the factions database table.

    3

    string

    Key of the diplomatic action, from the cai_personality_diplomatic_events database table.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3491

    cm:cai_insert_caravan_diplomatic_event(string event faction name, string caravan faction name)

    Inserts a diplomatic event for a caravan arriving for a given faction.

    Parameters:

    1

    string

    Name of the faction receiving the diplomatic event, from the factions database table.

    2

    string

    Name of the faction owning the caravan, from the factions database table.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3498

    cm:cai_disable_targeting_against_settlement(string settlement key)

    Disables the ability of the ai to target a settlement.

    Parameters:

    1

    string

    Settlement key, from the campaign_map_settlements database table.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3504

    cm:cai_enable_targeting_against_settlement(string settlement key)

    Enables the ability of the ai to target a settlement after it was disabled with cm:cai_disable_targeting_against_settlement.

    Parameters:

    1

    string

    Settlement key, from the campaign_map_settlements database table.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3509

    cm:cai_evaluate_quick_deal_action(faction proposing faction, faction recipient faction, string deal type)

    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

    faction

    proposing faction interface.

    2

    faction

    recipient faction interface.

    3

    string

    Deal type, from the diplomatic_actions database table.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3514

    Back to top

    AI Script Context

    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(string value)

    Sets the global script context value.

    Parameters:

    1

    string

    Value to set. Valid values are "DEFAULT", "ALPHA", "BETA", "GAMMA", "DELTA", "EPSILON" and "ZETA".

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3542

    cm:cai_get_global_script_context()
    Returns the current global script context value.

    Returns:

    1. string global script context value

    defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3547

    cm:cai_clear_global_script_context()
    Clears the current global script context value, setting it to "DEFAULT".

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3552

    cm:cai_set_faction_script_context(string faction key, string value)

    Sets the script context value for the specified faction.

    Parameters:

    1

    string

    Faction key, from the factions database table.

    2

    string

    Value to set. Valid values are "DEFAULT", "ALPHA", "BETA", "GAMMA", "DELTA", "EPSILON" and "ZETA".

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3556

    cm:cai_get_faction_script_context(string faction key)

    Returns the current script context value for the specified faction.

    Parameters:

    1

    string

    Faction key, from the factions database table.

    Returns:

    1. string script context value

    defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3562

    cm:cai_clear_faction_script_context(string faction key)

    Clears the script context value for the specified faction, setting it to "DEFAULT".

    Parameters:

    1

    string

    Faction key, from the factions database table.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3568

    Back to top

    AI Point of Interest Markers

    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(
          number poi group id,
      number     poi id,
      number     x,
      number     y,
      [string     faction key]
    )

    Adds a point of interest marker for the AI. An optional associated faction can be specified.

    Parameters:

    1

    number

    point-of-interest group identifier index.

    2

    number

    point-of-interest identifier index. This is the id within the group the POI belongs to.

    3

    number

    Logical x co-ordinate.

    4

    number

    Logical y co-ordinate.

    5

    string

    optional, default value=nil

    Key of associated faction, from the factions database table.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3585

    cm:cai_remove_point_of_interest_generic_marker(number poi group id, number poi id)

    Removes a point-of-interest marker based on its group id and id.

    Parameters:

    1

    number

    point-of-interest group identifier index.

    2

    number

    point-of-interest identifier index.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3594

    Back to top

    Metrics

    cm:trigger_performance_metrics_start()
    Start gathering timing information for metrics.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3615

    cm:trigger_performance_metrics_stop()
    Stop gather timing information for metrics and send.

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3619

    cm:trigger_scripted_tour_metrics_start(string tour name)

    Report that a scripted tour was started by a user.

    Parameters:

    1

    string

    tour name

    Returns:

    1. nil

    defined in ../../Warhammer/working_data/script/docgen/content/campaign/docgen_campaign_episodic_scripting.lua, line 3623

    Last updated 12/08/2022 11:56:58