Example Scripts
A list of example scripts that can easily be copied, edited and then put into a mod.
Using Example Scripts
Unless otherwise stated these scripts go into a .pack file at `script/campaign/mod/?.lua`, replace ? with whatever your file name is.
Each script listed is self-contained - so you can use multiple of the example scripts in a single .lua file.
When using the scripts, please keep the credits at the top and don't remove comments. Comments are the text following -- or in a comment block denoted by --Text here .
Typically an example script will have a list of variables that should be changed to tailor the script to your particular mod, these will often have comments next to them explaining where you will find the keys or values from.
Example in the Replace Starting General example script, you have a line that reads 'local faction_name = "wh_main_emp_empire";'
This could instead be changed to 'local faction_name = "wh2_dlc11_vmp_the_barrow_legion";' to affect the Barrow Legion faction instead of The Empire.
If there are out() calls within the example script, you are encouraged to insert a unique text identifier, so you can find your unique output in the script logs using ctrl+f.
Example in the Replacing Starting General Script, replace REPLAC: with your unique identifier, maybe the starting letters of your discord username, or the mod name or the name of your cat, or something else unique to you.
Contributing new scripts
If you have some generic scripted functionality you think would be useful for the wider community, please consider adding it to the wiki here, or bring attention to it via Modding Discord in the channel for the wiki.
Add a new Sub-Heading 1 within the Example Scripts section below, give it a meaningful title and a short description. Include what games it is valid for and any specific notes necessary, ie. has to go in this directory, has to be done this way etc.
Avoid using global variables in the example scripts, use local variables and local functions to avoid incidents involving scripts that have overlapping names. Make sure to use comments explaining what the various parts of the script is doing or when referring to specific keys from the database, like where to find them. Context and explanation goes a long way towards helping make sense of the scripts for beginners.
If your script runs through a single init function that's triggered through a first tick callback, give the local function a meaningful name and implement the first-tick-callback, and leave it at that. No need to have the modder replace the local function name in their own replication.
Mind that plopping something in this page leaves it open for collaboration, so someone in the future may come in and add more comments, change anything necessary for an update, make an extra version for another game, or much else. If you're editing the original script, leave the credits the same, or add your name to the credits if you think the addition is meaningful. Don't remove the OG author for sure.
Example Scripts
Replacing a Starting General
--[[
Script by Aexrael Dex
Replaces the starting general for a specific faction
]]
local function replace_starting_general()
if cm:is_new_game() then
-- The Empire
local faction_name = "wh_main_emp_empire"; -- Faction key from Factions table
local faction = cm:get_faction(faction_name);
if faction:is_null_interface() == false and faction:is_dead() == false then
-- Creating replacement for Karl Franz with a regular Empire General
local general_details = {
general_faction = faction_name,
unit_list = "wh_main_emp_cav_reiksguard,wh_main_emp_cav_reiksguard,wh_main_emp_cav_reiksguard"; -- unit keys from main_units table
region_key = faction:home_region():name(),
type = "general", -- Agent type
subtype = "emp_lord", -- Agent subtype
forename = "names_name_1904032251", -- From local_en names table, Bernhoff the Butcher is now ruler of Reikland
clanname = "", -- From local_en names table
surname = "names_name_151217003", -- From local_en names table
othername = "", -- From local_en names table
is_faction_leader = true, -- Bool for whether the general being replaced is the new faction leader
trait = "wh2_dlc09_trait_benevolence" -- The trait key you want to assign to the new General from character traits table
};
local general_x_pos, general_y_pos = cm:find_valid_spawn_location_for_character_from_settlement(general_details.general_faction, general_details.region_key, false, true, 8);
out(faction_name .. " home region name is " .. general_details.region_key);
cm:create_force_with_general(
general_details.general_faction,
general_details.unit_list,
general_details.region_key,
general_x_pos,
general_y_pos,
general_details.type,
general_details.subtype,
general_details.forename,
general_details.clanname,
general_details.surname,
general_details.othername,
general_details.is_faction_leader,
-- Generals created this way does not come with a trait normally
function(cqi)
local char_str = cm:char_lookup_str(cqi);
-- Adding a new trait to the above general
cm:force_add_trait(char_str, general_details.trait, true);
out("Adding Replacement General's trait");
end
);
out("Created replacement Lord " .. general_details.forename .. " for " .. faction_name);
-- Killing Karl Franz permanently
local char_list = faction:character_list();
local char_subtype = "emp_karl_franz"; -- Karl Franz's agent subtype
local char_forename = "names_name_2147343849"; -- Karl Franz's forename
for i = 0, char_list:num_items() - 1 do
local current_char = char_list:item_at(i);
local char_str = cm:char_lookup_str(current_char);
if current_char:is_null_interface() == false and current_char:character_subtype_key() == char_subtype and current_char:get_forename() == char_forename and current_char:has_military_force() == true then
cm:set_character_immortality(char_str, false);
cm:disable_event_feed_events(true, "wh_event_category_character", "", "");
cm:kill_character(current_char:command_queue_index(), true, true);
cm:callback(function() cm:disable_event_feed_events(false, "wh_event_category_character", "", "") end, 0.5);
out("Killing original " .. char_subtype .. " with forename " .. char_forename .. " for " .. faction_name .. " permanently");
end;
end;
end;
end;
end;
cm:add_first_tick_callback(function() replace_starting_general() end);
Adding custom RoRs to mercenary pool
--[[
Script by Aexrael Dex
Adds custom Regiments of Reknown to defined factions
]]
local function cror_initiator()
-- Checking whether the script has already run for saved games and if it has then the script doesn't need to run again
if cm:get_saved_value("custom_ror_enabled") == nil then
-- Table for faction, unit key and parameters for add_unit_to_faction_mercenary_pool
local cror_list = {
{faction = "wh_main_vmp_schwartzhafen", unit = "wh2_dlc11_cst_inf_zombie_deckhands_mob_ror_0", count = 1, rcp = 100, munits = 1, murpt = 0.1, xplevel = 0, frr = "", srr = "", trr = "", replen = false},
{faction = "wh_main_vmp_vampire_counts", unit = "wh2_dlc11_cst_inf_zombie_deckhands_mob_ror_0", count = 1, rcp = 100, munits = 1, murpt = 0.1, xplevel = 0, frr = "", srr = "", trr = "", replen = false}
};
-- Loop for the table above
for i = 1, #cror_list do
local faction_str = cror_list[i].faction; -- Faction whose pool the unit(s) should be added to
local faction_obj = cm:get_faction(faction_str); -- FACTION_SCRIPT_INTERFACE faction
local unit_key = cror_list[i].unit; -- Key of unit to add to the mercenary pool, from the main_units table
local unit_count = cror_list[i].count; -- Number of units to add to the mercenary pool
local rcp = cror_list[i].rcp; -- Replenishment chance, as a percentage
local munits = cror_list[i].munits; -- The maximum number of units of the supplied type that the pool is allowed to contain.
local murpt = cror_list[i].murpt; -- The maximum number of units of the supplied type that may be added by replenishment per-turn
local xplevel = cror_list[i].xplevel; -- The experience level of the units when recruited
local frr = cror_list[i].frr; -- (may be empty) The key of the faction who can actually recruit the units, from the factions database table
local srr = cror_list[i].srr; -- (may be empty) The key of the subculture who can actually recruit the units, from the cultures_subcultures database table
local trr = cror_list[i].trr; -- (may be empty) The key of a technology that must be researched in order to recruit the units, from the technologies database table
local replen = cror_list[i].replen; -- Allow replenishment of partial units
-- Adding the listed unit to the listed faction in the above table
cm:add_unit_to_faction_mercenary_pool(faction_obj, unit_key, unit_count, rcp, munits, murpt, xplevel, frr, srr, trr, replen);
-- Setting saved value, so that the script doesn't run again when reloaded from a saved game
cm:set_saved_value("custom_ror_enabled", true);
-- Debug message for log
out("adding the custom ror unit " .. unit_key .. " to " .. faction_str);
end;
end;
end;
cm:add_first_tick_callback(function() cror_initiator() end);
Replacing Starting Armies
--[[
Script by Aexrael Dex
Replaces the starting units for the designated characters
]]
-- Rename edit_starting_army
local function edit_starting_army()
if cm:is_new_game() then
local custom_starting_army = {
-- Vlad, Carsteins
{faction = "wh_main_vmp_schwartzhafen", subtype = "dlc04_vmp_vlad_con_carstein", forename = "names_name_2147345130", units = {"wh_main_vmp_inf_skeleton_warriors_0", "wh_main_vmp_inf_skeleton_warriors_0", "wh_main_vmp_mon_fell_bats", "wh_main_vmp_mon_fell_bats", "wh_main_vmp_cav_black_knights_0", "wh_main_vmp_cav_black_knights_0"}},
-- Isabella, Carsteins
{faction = "wh_main_vmp_schwartzhafen", subtype = "pro02_vmp_isabella_von_carstein", forename = "names_name_2147345124", units = {"wh_main_vmp_inf_zombie", "wh_main_vmp_inf_zombie", "wh_main_vmp_mon_dire_wolves", "wh_main_vmp_mon_dire_wolves", "wh_main_vmp_mon_fell_bats", "wh_main_vmp_mon_vargheists"}}
};
for i = 1, #custom_starting_army do
local faction_str = custom_starting_army[i].faction;
local faction_obj = cm:get_faction(faction_str);
local char_list = faction_obj:character_list();
local general_subtype = custom_starting_army[i].subtype;
local general_forename = custom_starting_army[i].forename;
local unit_list = custom_starting_army[i].units;
for j = 0, char_list:num_items() - 1 do
local current_char = char_list:item_at(j);
if current_char:is_null_interface() == false and current_char:character_subtype_key() == general_subtype and current_char:get_forename() == general_forename and current_char:has_military_force() == true then
cm:remove_all_units_from_general(current_char);
out("Removing starting units from " .. general_subtype .. " with forename " .. general_forename);
for k = 1, #unit_list do
local unit = unit_list[k];
cm:grant_unit_to_character(cm:char_lookup_str(current_char:cqi()), unit);
out("Granting new starting units to " .. general_subtype .. " with forename " .. general_forename);
end;
end;
end;
end;
end;
end;
-- Rename edit_starting_army to match the function name at the top
cm:add_first_tick_callback(function() edit_starting_army() end);