Example Scripts

A list of example scripts that can be easily copied, edited, and then pasted into a mod for quick functionality. Typically will have a block of variables to edit the values of for your own version.

If using these scripts, keep the credits at the top for the original author.

If making new scripts, make sure you are using good practices -

Examples

Replacing a Starting General

--[[
	Script by Aexrael Dex
	Replaces the starting general for a specific faction
]]

-- Rename replace_starting_general
local function replace_starting_general()
	if cm:is_new_game() then

		-- Creating replacement for Karl Franz with a regular Empire General
		local general_faction_str = "wh_main_emp_empire"; -- faction key from factions table
		local general_faction_obj = cm:get_faction(general_faction_str);
		local general_unit_list = "wh_main_emp_cav_reiksguard,wh_main_emp_cav_reiksguard,wh_main_emp_cav_reiksguard"; -- unit keys from main_units table
		local general_region_key = general_faction_obj:home_region():name(); -- the replacement general will spawn adjacent to the settlement in the home region for the faction
		local general_x_pos, general_y_pos = cm:find_valid_spawn_location_for_character_from_settlement(
			general_faction_str,
			general_region_key,
			false,
			true
		);
		local general_type = "general";						-- agent type
		local general_subtype = "emp_lord";					-- agent subtype
		local general_forename = "names_name_1904032251";	-- from local_en names table, Bernhoff the Butcher is now ruler of Reikland
		local general_clanname = "";						-- from local_en names table
		local general_surname = "";							-- from local_en names table
		local general_othername = "";						-- from local_en names table
		local general_is_faction_leader = true;				-- bool for whether the general being replaced is the new faction leader

		cm:create_force_with_general(
			general_faction_str,
			general_unit_list,
			general_region_key,
			general_x_pos,
			general_y_pos,
			general_type,
			general_subtype,
			general_forename,
			general_clanname,
			general_surname,
			general_othername,
			general_is_faction_leader,

			-- Generals created this way does not come with a trait and aren't immortal
			function(cqi)
				local char_str = cm:char_lookup_str(cqi);
				-- Adding a new trait to the above general
				cm:force_add_trait(char_str, "wh2_dlc09_trait_benevolence", true);
				out("Adding a trait to " .. general_forename);

				-- Making the new general immortal (!!Use Skill based immortality instead!!)
				cm:set_character_immortality(char_str, true);
				out("Making general with forename " .. general_forename .. " immortal");
			end
		);
		out("Creating Neo_Karl Franz for Reikland");

		-- Killing original Karl Franz
		local char_list = general_faction_obj:character_list();
		local leader_subtype = "emp_karl_franz"; -- Karl Franz's agent subtype
		local leader_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);

			if current_char:is_null_interface() == false and current_char:character_subtype_key() == leader_subtype and current_char:get_forename() == leader_forename and current_char:has_military_force() == true then
				cm:set_character_immortality("character_cqi:"..current_char:command_queue_index(), false); -- Removing Karl Franz's immortality
				cm:disable_event_feed_events(true, "wh_event_category_character", "", ""); -- Disabling event feed messages for character related events
				cm:kill_character(current_char:command_queue_index(), true, true); -- Killing Karl Franz
				cm:callback(function() cm:disable_event_feed_events(false, "wh_event_category_character", "", "") end, 1); -- Enabling event feed messages for character related events
				out("Killing original " .. leader_subtype .. " with forename " .. leader_forename .. " for " .. general_faction_str .. " permanently");
			end;
		end;
	end;
end;

-- Rename replace_starting_general to match the function name at the top
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);