Campaign Custom Starts

Allows tweaks to be made to a faction's starting circumstances based on other conditions.

This script is to be used when creating a custom start that differs from the start_pos.

Please use this instead of editing a faction's unique start/prelude scripts - editing that file with start pos changes can only be done in SP as MP changes cause desync issues.

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

How to Use

To use the custom start functions you need to declare a set of changes to enact in the custom_start table.

Within a custom start, a set of changes to the campaign map can be specified. For example, region_change can give a region to a particular faction.

The conditions under which a certain custom start executes can be defined with the is_human and is_ai values. These may be a faction string, or a list of faction strings, and ALL factions must be human, or AI, for is_human and is_ai respectively.

Example - Custom Start:

For Cult of Sotek, if Pestilens is AI then start war between Sotek and Pestilens, and give Pestilens the Shrine of Sotek. If Itza and Cult of Sotek are AI, they cannot declare war.
{
    if_human = "wh2_dlc12_lzd_cult_of_sotek",
    if_ai = "wh2_main_skv_clan_pestilens",
    changes = {
        {"region_change", "wh3_main_combi_region_shrine_of_sotek", "wh2_main_skv_clan_pestilens"},
        {"force_diplomacy", "wh2_dlc12_lzd_cult_of_sotek", "wh2_main_skv_clan_pestilens", "war"},
    }
}
{
    if_ai = { "wh2_dlc12_lzd_cult_of_sotek", "wh2_main_lzd_itza" }
    changes = {
        {"block_diplomacy", "wh2_dlc12_lzd_cult_of_sotek", "wh2_main_lzd_itza", "war", false, false},
    }
}

custom_starts:region_change(string region key, string faction_name)

Give a region to the specified faction.

Parameters:

1

string

The key of the region to be transferred.

2

string

The key of the faction to receive the region.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/campaign/wh2_campaign_custom_starts.lua, line 348

custom_starts:absorb_other_faction(string absorbing faction key, string absorbed_faction_key)

Give all regions of the absorbed faction to the absorbing faction, and kill all absorbed faction's characters.

Parameters:

1

string

The key of the faction to absorb the other faction.

2

string

The key of the faction to be absorbed.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/campaign/wh2_campaign_custom_starts.lua, line 373

custom_starts:primary_slot_change(string region, string building)

Change the primary building at the specified region to the specified building.

Parameters:

1

string

The region at which the building should be changed.

2

string

The building to set the primary slot of the region to.

Returns:

  1. boolean Returns true of the primary slot successfully changed to the specified building key, otherwise returns false.

defined in ../../Warhammer/working_data/script/campaign/wh2_campaign_custom_starts.lua, line 400

custom_starts:port_slot_change(string region, string building)

Change the port slot at the specified region to the specified building.

Parameters:

1

string

The key of the region at which the port slot will change.

2

string

The key of the building to change the slot to.

Returns:

  1. boolean Returns true of the primary slot successfully changed to the specified building key, otherwise returns false.

defined in ../../Warhammer/working_data/script/campaign/wh2_campaign_custom_starts.lua, line 430

custom_starts:secondary_slot_change(string region, number slot_index, string building)

Change the secondary slot at the given index of a specified region to a building.

Parameters:

1

string

The key of the region at which to change the building.

2

number

The zero-based index of the secondary slot at which to change the building.

3

string

The key of the building to which the slot should change.

Returns:

  1. boolean Returns true of the primary slot successfully changed to the specified building key, otherwise returns false.

defined in ../../Warhammer/working_data/script/campaign/wh2_campaign_custom_starts.lua, line 466

custom_starts:create_army(
  string faction_name,
  number or string unit_list,
  string region_name,
  number x_pos,
  number y_pos,
  string agent_subtype,
  boolean is_leader,
  table name_table
)

Spawn an army on the map for a certain faction using either a quantity of units, or a random army template key.

Parameters:

1

string

The key of the faction the army will belong to.

2

number

The quantity of units to be spawned (in which case random units are created) or the key of the random army template to be used.

3

string

The key of the region the army will spawn in.

4

number

The x coordinate the army will spawn at.

5

number

The y coordinate the army will spawn at.

6

string

Character subtype of character at the head of the army.

7

boolean

Make the spawned character the faction leader.

8

table

An array of 4 names, corresponding to the forename, clan name, family name, and other name of the general. Unfilled names must be empty strings. These should be given in the localised text lookup format i.e. a key from the names table with "names_name_" prepended.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/campaign/wh2_campaign_custom_starts.lua, line 509

custom_starts:create_army_for_faction_leader(
  string faction_name,
  string region_name,
  number x_pos,
  number y_pos,
  number or string unit_list
)

Create an army for the leader of the specified faction.

Parameters:

1

string

The key of the faction whose leader gets an army.

2

string

The key of the region the army will spawn in.

3

number

The x coordinate at which the army will spawn.

4

number

The y coordinate at which the army will spawn.

5

number

The quantity of units to be spawned (in which case random units are created) or the key of the random army template to be used.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/campaign/wh2_campaign_custom_starts.lua, line 597

custom_starts:teleport_character(
  string faction_name,
  number start_x,
  number start_y,
  number end_x,
  number end_y,
  boolean is_general
)

Teleport a character of a given faction, whichever character is closest to the provided start coordinates.

Parameters:

1

string

The key of the faction the teleported character belongs to.

2

number

The starting x coordinate - the closest character of the given faction to this position will be teleported.

3

number

The starting y coordinate - the closest character of the given faction to this position will be teleported.

4

number

The teleport x coordinate.

5

number

The teleport y coordinate.

6

boolean

Whether or not the target character is a general. This informs which character nearest the starting coord is selected.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/campaign/wh2_campaign_custom_starts.lua, line 651

custom_starts:teleport_character_faction_leader(string faction_key, number target_x, number target_y)

Teleport the leader of the specified faction to these coordinates.

Parameters:

1

string

The name of the faction whose leader is to be teleported.

2

number

The x coordinate to teleport to.

3

number

The y coordinate to teleport to.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/campaign/wh2_campaign_custom_starts.lua, line 703

custom_starts:hide_faction_leader(string faction_key, number startpos_ID, boolean kill_army)

Hide the leader of the faction by killing them and restricting their recruitment.

Parameters:

1

string

The key of the faction whose leader will be hidden.

2

number

The startpos ID of the general to have their recruitment locked. This ought to match the leader of the specified faction.

3

boolean

Kill the faction leader's entire army, if true.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/campaign/wh2_campaign_custom_starts.lua, line 717

custom_starts:modify_units_in_army(
  string faction_name,
  number pos_x,
  number pos_y,
  table add_units_table,
  table remove_units_table,
  [string general_forename],
  [string general_surname]
)

Add and remove the provided lists of units (removals occur per-instance, so three consecutive unit keys results in the removal of 3 units), to the factions' army found closest to the provided coordinate.

Parameters:

1

string

The key of the faction for which armies close to the coordinates will be considered.

2

number

The x coordinate close to the target army.

3

number

The y coordinate close to the target army.

4

table

A list of unit keys to be added. Provide an empty table if no units wanted.

5

table

A list of unit keys to be removed, per-instance of that unit. Provide an empty table if no units wanted.

6

string

optional, default value=nil

The forename of the general whose army will be adjusted. Can be used to handle different starting generals for the same faction receiving different starting units. Otherwise can be left blank.

7

string

optional, default value=nil

The surname of the general whose army will be adjusted.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/campaign/wh2_campaign_custom_starts.lua, line 735

custom_starts:add_xp_to_units(string faction_name, string unit_key, number experience)

Add XP to each instance of the given unit key in all of a faction's armies.

Parameters:

1

string

The faction for which all units of a type will receive XP.

2

string

The key of the unit type to receive XP.

3

number

The amount of XP given to each unit.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/campaign/wh2_campaign_custom_starts.lua, line 806

custom_starts:force_diplomacy_change(string s_faction, string t_faction, string d_type)

Force a change in diplomacy between the two factions.

Parameters:

1

string

The source faction.

2

string

The target faction.

3

string

The type of diplomacy to enforce. This is currently limited to 'peace' or 'war'. Allies are not invited to war.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/campaign/wh2_campaign_custom_starts.lua, line 845

custom_starts:block_diplomacy(
  string s_faction,
  string t_faction,
  string diplomacy,
  boolean can_offer,
  boolean can_offer
)

Restricts or unrestricts diplomacy types between two factions, using the diplomacy types available in campaign_manager:force_diplomacy. Groups of factions may be specified with the strings "all", "faction:faction_key", "subculture:subculture_key" or "culture:culture_key".

Parameters:

1

string

The source faction.

2

string

The target faction.

3

string

The diplomacy type being restricted or allowed, as specified in campaign_manager:force_diplomacy.

4

boolean

If the source faction can offer this diplomatic relationship to the target.

5

boolean

If the source faction can accept this diplomatic relationship to the target.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/campaign/wh2_campaign_custom_starts.lua, line 878

custom_starts:abandon_region(string region_key)

Abandon the specified region key, turning it to ruins.

Parameters:

1

string

The key of the region to be abandoned.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/campaign/wh2_campaign_custom_starts.lua, line 919

custom_starts:kill_faction(string faction_key)

Kills the specified faction key, abandoning all its regions and killing all armies.

Parameters:

1

string

The key of the faction to be killed.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/campaign/wh2_campaign_custom_starts.lua, line 936

custom_starts:apply_effect_bundle_character(
  string faction_name,
  number x_pos,
  number y_pos,
  number bundle,
  number duration
)

Apply an effect bundle to the character of the specified faction nearest the provided location.

Parameters:

1

string

The key name of the faction for which characters will be considered.

2

number

The x coordinate from which the target character is searched.

3

number

The y coordinate from which the target character is searched.

4

number

The key of the bundle to apply.

5

number

The turn duration the bundle will last for, 0 being infinite turns.

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/campaign/wh2_campaign_custom_starts.lua, line 990

custom_starts:force_change_faction_cai_personality(string faction_key, string personality_key)

Force the specified faction to adopt the specified AI personality.

Parameters:

1

string

Faction key

2

string

Personality key

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/campaign/wh2_campaign_custom_starts.lua, line 1035

custom_starts:add_pooled_resource_to_faction(
  string faction_name,
  string pooled_resource_key,
  string pooled_resource_factor_key,
  number, the amount to adjust by
)

Adjusts specified pooled resource to target faction.

Parameters:

1

string

The faction name to adjust the specified pooled resource for.

2

string

The pooled resource to adjust values for.

3

string

The factor through which the resource is adjusted for the faction

4

number,

the amount to adjust by

Returns:

  1. nil

defined in ../../Warhammer/working_data/script/campaign/wh2_campaign_custom_starts.lua, line 1045

custom_starts:generate_random_army(string subculture, number num_units)

Generate a random army using pre-defined army sets per subculture.

Parameters:

1

string

The subculture of the army to be generated: each subculture has a particular 'standard' army template in this function.

2

number

The size of the army to be generated.

Returns:

  1. string Returns a table of unit keys representing the army that was generated.

defined in ../../Warhammer/working_data/script/campaign/wh2_campaign_custom_starts.lua, line 1068

Last updated 12/08/2022 11:56:58