Total War Modding - User contributions [en]

Tutorial:Creating & Editing .Wsmodels

2022-01-22T19:17:20Z

Fenriswolf: included the missing pictures and introduced blocks for the wsmodels

=== Originally by Shawmuscle ===
This guide aims to show you how to edit and create .wsmodel files, this will enable you to change the color of hexwraiths, chaos weapons and much more. You will be able to edit the effects that are directly associated with the models in warhammer.

== Things you will need ==
RPFM -(recommended) <nowiki>https://github.com/Frodo45127/rpfm/releases</nowiki>

Unwrap 3D (dont have to have this, just makes life easy) <nowiki>https://www.unwrap3d.com/u3d/index.aspx</nowiki>

Gimp

<nowiki>https://www.gimp.org/downloads/</nowiki>

From here we can start to create the .wsmodel files

I will be selecting a model that currently has no .wsmodel as this will enable you deal with all the possibilities, I will also be showing you how to use glows and effects in the material file and how you can have a material file that allows both the deletion of parts from any model (helmets cause some issues) as well as add effects to them. Next section please!

== Get files and create .wsmodel ==
To start we will be using Karl franz model, why this one? This is a good model as it presents quite a few challenges that not all models have, which I will show you. Comments

So go ahead and open RPFM.

create a new mod if you dont currently have one.
or
you can use mine here – <nowiki>https://drive.google.com/open?id=19d8tciXLkGjzl9k5ig6aepATJrsFEvuq</nowiki>

open the “campaign_variants” file

[[File:wsmodel_0_5.png|frameless|697x697px]]

Now open up variants_dds2.pack and extract the “tex” file associated with Karl Franz. like this-

[[File:Wsmodels-1.jpg|frameless|697x697px]]

now we have what the vanilla files can offer us.

== The Next Step ==
Next we are going to go ahead an just make the .wsmodel and later we will edit it and show you why you will want to start using .wsmodel files.

Using RPFM Create a new folder called “materials” Like this-

[[File:Wsmodels-2.jpg|frameless|697x697px]]

you now have 2 options,

====== Option 1 (not recommended but worth mentioning) ======

:: Using Rpfm open up variants or campaign variants and find a unit that has some material files, extract them and import into your mod under the tab “materials”

=== OR ===
====== Option 2 (recommended) ======

:: You can use my material files which do not have limitations as many others in vanilla do – you can find those here-

<nowiki>https://drive.google.com/open?id=1tdaFdxaa6OSrAi7Jbk_89ZZnfNowkp-K</nowiki>

import those material files into your mod, should look like this –

[[File:Wsmodels-3.jpg|frameless|697x697px]]

Great! Now we need a .wsmodel file! We will get into the editing of the material files later.

Using RPFM pick a .wsmodel from anyone, you are going to change it so it doesnt matter which. for easy pickings try Green Knight in bret.

Should have a mod that looks something like this –

[[File:Wsmodels-4.jpg|frameless|697x697px]]

the next step is to open the rigid model v2 file in 3D unwrap but this will allow you to see how many parts there are to a model

like so

[[File:Wsmodels-5.jpg|frameless|697x697px]]

as you can see in the right hand side there are 2 parts to this one rigid model file, so we will need to create a .wsmodel file that refers to 2 parts

<code> <model version=”1″>
<geometry>variantmeshes/wh_variantmodels/hu1/emp/emp_karl_franz/theodric_karl_franz.rigid_model_v2</geometry>
<materials>
<material lod_index=”0″ part_index=”1″>VariantMeshes/wh_variantmodels/hu1/emp/emp_karl_franz/materials/emp_karl_franz_head_01_weighted4.xml.material</material>
<material lod_index=”1″ part_index=”1″>VariantMeshes/wh_variantmodels/hu1/emp/emp_karl_franz/materials/emp_karl_franz_head_01_weighted4.xml.material</material>
<material lod_index=”2″ part_index=”1″>VariantMeshes/wh_variantmodels/hu1/emp/emp_karl_franz/materials/emp_karl_franz_head_01_weighted2.xml.material</material>
<material lod_index=”3″ part_index=”1″>VariantMeshes/wh_variantmodels/hu1/emp/emp_karl_franz/materials/emp_karl_franz_head_01_weighted2.xml.material</material>
<material lod_index=”0″ part_index=”0″>VariantMeshes/wh_variantmodels/hu1/emp/emp_karl_franz/materials/emp_karl_franz_body_01_weighted4.xml.material</material>
<material lod_index=”1″ part_index=”0″>VariantMeshes/wh_variantmodels/hu1/emp/emp_karl_franz/materials/emp_karl_franz_body_01_weighted4.xml.material</material>
<material lod_index=”2″ part_index=”0″>VariantMeshes/wh_variantmodels/hu1/emp/emp_karl_franz/materials/emp_karl_franz_body_01_weighted2.xml.material</material>
<material lod_index=”3″ part_index=”0″>VariantMeshes/wh_variantmodels/hu1/emp/emp_karl_franz/materials/emp_karl_franz_body_01_weighted2.xml.material</material>
</materials>
</model> </code>

here you can use mine.

As you can see I have my “lod” indexes 0-3, always do 4 lods and then I have referenced “part index” 0 and 1 the head being part index 1 and the body being part index 0. I know to put 2 parts as we opened the file in Unwrap 3D.

Awesome! now we have a .wsmodel file! But there is still some work to be done in the material files which I will now show you.

== Editing the Material files ==
Ok for those of you who used Option 1 you will have to spend some time figuring out which material files will work with karl franz, once you have found one, reference karls .dds files in the material file. The important part of the material files to look at are there it says which shader it is.
I will reference a few and try to give some info on which types do what

<code> <name>chs_sorcerer_legs_01_weighted4_alpha_on.xml</name>
<shader>shaders/weighted4_faction_colours_skin_alpha.xml.shader</shader> </code>

This shader is used for a lot of units, it enables the deletion of parts but does not allow glow effects. Also notice where it says “weighted4” super important for armours/bodies as most of the time the lods will reference a “weighted2” and a “weighted4”, its best to look at vanilla wsmodel to be sure but if you are creating a new file reference both in your .wsmodel.

another type of shader you will find is-

<code> <name>chs_archaon_head_01_weighted2.xml</name>
<shader>shaders/weighted2_tinted_metal_emissive_optimized.xml.shader</shader> </code>

As we all know Archaons head is lit up like a Christmas tree, you guessed it…this shader enables glow effects but does not allow the deletion of parts using the alpha channel. Something that sucks about this one is that it doesnt say “alpha on” or “alpha off” but it usually works that if it enables a glow you cannot use it to delete a part and vice versa.

There are hundreds to choose from so have a search and test what they do, change some values try different stuff out. I made my own material files to work for all purposes as I got frustrated with searching through the shaders endlessly.

For those who took my material files you should be looking at something like this –

[[File:wsmodel_5_5.png|frameless|697x697px]]

as you can see I have highlighted the line that is referring to the diffuse file, all you need to do to use the vanilla files is go down the list of .dds files and reference

<code> VariantMeshes/wh_variantmodels/hu1/emp/emp_karl_franz/tex/emp_karl_franz_body_01_diffuse.dds </code>

and do this for gloss map,normal,specular and mask dds files.

but if you are wanting to use your own .dds file you have created reference them here, as I have done in the picture above.

Do this for all the material files. You will find that by using my custom material files the diffuse does not get seen and your colors may look a little off, so simply darken your specular .dds file to achieve the same result. (I will show you later why you will want to be using my material files)

now you have that, all you need to do is reference your material files in your .wsmodel file that you made earlier. Then go to variant mesh definitions\ “emp_ch_karl.variantmeshdefinition” and paste in your new .wsmodel file

like this –

[[File:Wsmodels-6.jpg|frameless|697x697px]]

[[File:wsmodel_6_5.png|frameless|697x697px]]

great! If all you wanted to do was create a .wsmodel file and not edit glows or delete parts etc. you are done! Whoooo! good for you guys.

For those interested in the possibilities of a .wsmodel file and why we use them carry on reading ;)

== Creating glows & Removing body parts ==
Ok so this is why I like using .wsmodels, they enable us to do some really cool things.
We are going to delete Karl franz head an replace with a different one.

to start I will be showing you something simple and what I imagine most modders know how to do using Rigid model v2 files. Its pretty simple, using my material files that I left a link to earlier, or some people may want to use vanilla files, if you do, pick ones that use '''Alpha_on''' as this is what enables us to delete body parts, if you are using one that says '''Alpha_off''' then you cannot remove body parts. hence why I made a material file that does both.

anyway using my material file, you want to open up karl franz head diffuse file in GIMP looks like this – then go ahead and delete everything in there looks like this –

[[File:Wsmodels-7.jpg|frameless|697x697px]]

[[File:Wsmodels-8.jpg|frameless|697x697px]]

now save it as whatever your heart desires, ideally not the same as karl_franz vanilla... unless you are editing karl franz to have no head.

import you new diffuse.dds file back into your mod.

Referencing it in the “emp_karl_franz_head_01_weighted2.xml.material” and “emp_karl_franz_head_01_weighted4.xml.material” files like so –

[[File:wsmodel_7_5.png|frameless|697x697px]]

this will now have removed his head. But we are replacing it, so in the variant mesh definition add a head from another unit, here is a character Ive already made as an example.

<code> <VARIANT_MESH>
<SLOT name=”tophat” >
<VARIANT_MESH model=”VariantMeshes/wh_variantmodels/hu1/tmb/tmb_tomb_guard/head/slv_tomb_guard_head_03.rigid_model_v2″ />
</SLOT>
<SLOT name=”faceness” >
<VARIANT_MESH model=”VariantMeshes\wh_variantmodels\hu1\brt\brt_lord\head\ude_lord_head_01.rigid_model_v2″ />
</SLOT>
<SLOT name=”body” >
<VARIANT_MESH model=”VariantMeshes\wh_variantmodels\hu1\emp\emp_karl_franz\theodric_body_01.wsmodel” >
<META_DATA>audio_entity_type:wh_human_male_LH</META_DATA>
<META_DATA>audio_armour_type:plate</META_DATA>
<META_DATA>audio_actor_id:actor_16</META_DATA></VARIANT_MESH>
</SLOT>
<SLOT name=”weapon_1″ attach_point=”be_prop_0″ />
<SLOT name=”weapon_2″ attach_point=”be_prop_1″ >
<VARIANT_MESH model=”VariantMeshes\wh_variantmodels\hu1\emp\emp_props\emp_arch_lector_hammer_1h_01.rigid_model_v2″ >
<META_DATA>audio_melee_weapon_type:hammer</META_DATA></VARIANT_MESH>
</SLOT>
<SLOT name=”shield” attach_point=”be_prop_2″ />
<SLOT name=”weapon_3″ attach_point=”be_prop_3″ />
<SLOT name=”weapon_4″ attach_point=”be_prop_4″ />
<SLOT name=”weapon_5″ attach_point=”be_prop_5″ >
<VARIANT_MESH model=”VariantMeshes\wh_variantmodels\hu1\emp\emp_props\emp_arch_lector_hammer_1h_01.rigid_model_v 2″ >
<META_DATA>audio_melee_weapon_type:hammer</META_DATA></VARIANT_MESH>
</SLOT>
</VARIANT_MESH> </code>

as you can see I added 2 extra models together to make a new head, looks like this

[[File:Wsmodels-9.jpg|frameless|697x697px]]

which is cool but you can already do this using the vanilla files, or a Rigid_v2 file.

I will show you how using the .wsmodel combined with my material files, can create units that are completely unique.

So far we have removed the head of the model karl franz and replaced it, but in a .wsmodel, we will now learn how to add effects like Durthu has or a hexwraith to any unit and to specific parts of each model.

Going back to Gimp open up karl franz body diffuse file, do a save as on this but save it as a ” (yourcharcternamehere)_mask.dds” looks like this

[[File:Wsmodels-10.jpg|frameless|697x697px]]

now create a new layer and using a BLACK brush draw on where you would like to see a glow effect here is my example –

[[File:wsmodel_10_5.png|frameless|697x697px]]

I just drew a big T on the cape. Now delete the bottom layer. should now only have the T left, like so

[[File:Wsmodels-11.jpg|frameless|697x697px]]

here is where people trip up, this will work but it will be a very solid and almost uncomfortable look, we can actually create a gradient (man im tired) using the mask file there are 2 things that effect this, one is the mask file itself and second is located within the material file itself under

<code> <name>emissive_strength</name>
<type>float</type>
<value>0.75</value> </code>

so using the mask file create a blank layer underneath this one like so –

[[File:wsmodel_11_5.png|frameless|697x697px]]

notice how now it looks faint, what this does is lessen the active effect and how strong it is in certain parts,if you want stronger glow in the center make it darker there than on the edges etc. this will enable you to create effects like the chaos weapons have the key is to

Save as “BC3 / DXT5” –

[[File:Wsmodels-12.jpg|frameless|697x697px]]

Now you have your new mask.dds file made just for Karl Franz, go ahead and import it then reference it in your material file using the correct file paths

to change the color of the effect you have to change the RGB values in the material file located here –

[[File:Wsmodels-13.jpg|frameless|697x697px]]

<code> <name>emissive_tint</name>
<type>float3</type>
<value>100,0,0</value> </code>

this would show a red glow, the middle is green and the right value is blue etc. If the colors are showing too strong or too weak try editing the emissive strength value which I referenced earlier.

Ok now give it a go should have a glow that is in a T shape on the cape of Karl franz. Boom Finished! Enjoy life now that you know a little more than you did before

But this is just the surface of possibilities. here are some units I have made using .wsmodel files

[[File:Wsmodels-14.jpg|frameless|697x697px]]

[[File:Wsmodels-15.jpg|frameless|697x697px]]

[[File:Wsmodels-16.jpg|frameless|697x697px]]

[[File:Wsmodels-17.jpg|frameless|697x697px]]

== Notes n Stuff ==
Hey guys hope you enjoyed the guide and learnt something new, if you know something I dont and think it needs to be in this guide let me know! I would love know and share that with others!

When your .wsmodel files are not working 90% of the time its a file path error you messed up

somewhere I guarantee it! Sometimes is your “lods” and “parts” and in some cases it the shader you are trying to use.

This tip comes from Chaos robbie, so thank you you him

Super Tip: If you’re getting that washed-out bug when using wsmodels it’s because your .dds formats are wrong. Here are the Intel Texture Works v1.0.4 settings that work 100% of the time:

* for Diffuse use Color and BC7 8 bpp Fine (sRGB, DX11++)

o or if you have an alpha channel use Color+Alpha and BC7 8 bpp Fine (sRGB, DX11++)

* for Specular use the same
* for Gloss Map you use Color and BC1 4bpp (Linear)
* for Normal Map you use Color+Alpha and BC1 4bpp (Linear)

the best advice I can give is dont give up, keep trying different stuff, we are all still new to this .wsmodel stuff, who knows you may find something new.

If you get stuck you can ask here but I am much more likely to reply on the Discord here – <nowiki>https://discord.gg/62retHM</nowiki>

If I do not answer someone else like Cataph or Marthenil will be able to help you.

which reminds me, this guide would not be possible if not for the discord, so thanks to everyone who has helped and answered my questions.
[[Category:Needs Formatting]]
[[Category:Needs Review]]

File:Wsmodel 11 5.png

2022-01-22T18:06:04Z

Fenriswolf:

File:Wsmodel 10 5.png

2022-01-22T18:05:42Z

Fenriswolf:

File:Wsmodel 7 5.png

2022-01-22T17:44:55Z

Fenriswolf:

File:Wsmodel 6 5.png

2022-01-22T17:32:47Z

Fenriswolf:

File:Wsmodel 5 5.png

2022-01-22T17:32:34Z

Fenriswolf:

File:Wsmodel 0 5.png

2022-01-22T17:10:06Z

Fenriswolf:

Example Scripts

2022-01-18T21:42:41Z

Fenriswolf: Fixed the broken link

A list of example scripts that can easily be copied, edited and then put into a [[Mods|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 [[Lua:Debugging|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 ===

<nowiki>
--[[
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);</nowiki>

=== Adding RoRs to mercenary pool ===

<nowiki>--[[
Script by Aexrael Dex
Adds custom Regiments of Reknown to specified factions
]]

local function add_custom_ror()

-- 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_key = "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 = true},
{faction_key = "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 = true}
};

-- Loop for the table above
for i = 1, #cror_list do
local faction_name = cror_list[i].faction_key; -- Faction whose pool the unit(s) should be added to
local faction = cm:get_faction(faction_name); -- FACTION_SCRIPT_INTERFACE
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, unit_key, unit_count, rcp, munits, murpt, xplevel, frr, srr, trr, replen);

-- Debug message for log
out("CROR: adding the custom ror unit " .. unit_key .. " to " .. faction_name);
end;

-- 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);
end;
end;

cm:add_first_tick_callback(function() add_custom_ror() end);</nowiki>

=== Replacing Starting Armies ===

<nowiki>--[[
Script by Aexrael Dex
Replaces the starting units for specified starting Lords
]]

local function army_tweaks()

-- Checking whether it's a new game, we don't want to replace armies in the middle of a campaign
if cm:is_new_game() then

-- Creating a table with entries for the various starting Lords, their Faction key from Factions table, subtype key from agent_subtypes, Forename from names table and Unit List with keys from Main Units
local starting_army = {
-- Vlad, Carsteins
{faction_key = "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_key = "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, #starting_army do
local faction_name = starting_army[i].faction_key;
local faction = cm:get_faction(faction_name);
local char_list = faction:character_list();
local general_subtype = starting_army[i].subtype;
local general_forename = starting_army[i].forename;
local unit_list = starting_army[i].units;

for j = 0, char_list:num_items() - 1 do
local current_char = char_list:item_at(j);
local char_str = cm:char_lookup_str(current_char);

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

-- Removing all existing units from the General
cm:remove_all_units_from_general(current_char);
out("ARMY: Removing starting units from " .. general_subtype .. " with forename " .. general_forename);

for k = 1, #unit_list do
local unit = unit_list[k];

-- Granting new units to the General
cm:grant_unit_to_character(char_str, unit);
out("ARMY: Adding new starting units to " .. general_subtype .. " with forename " .. general_forename);
end;
end;
end;
end;
end;
end;

cm:add_first_tick_callback(function() army_tweaks() end);</nowiki>

=== Changing CAI based on campaign difficulty ===

<nowiki>--[[
Script by Aexrael Dex
Replaces the Campaign AI Personality for specific factions depending on the chosen campaign difficulty level
]]

local function replace_cai_difficulty()
if cm:is_new_game() == true then
local difficulty_str = cm:get_difficulty(true);
local def_personality = "";
local hef_personality = "";
local wef_personality = "";

-- CAI personality to use for easy difficulty
if difficulty_str == "easy" then

def_personality = "wh2_darkelf_early_easy";
hef_personality = "wh2_highelf_early_easy";
wef_personality = "wh_dlc05_wood_elves_default_main";

-- CAI personality to use for normal difficulty
elseif difficulty_str == "normal" then

def_personality = "wh2_darkelf_early";
hef_personality = "wh2_highelf_early";
wef_personality = "wh_dlc05_wood_elves_default_main";

-- CAI personality to use for hard difficulty
elseif difficulty_str == "hard" then

def_personality = "wh2_darkelf_early_hard";
hef_personality = "wh2_highelf_early_hard";
wef_personality = "wh_dlc05_wood_elves_default_main";

-- CAI personality to use for very hard difficulty
elseif difficulty_str == "very hard" then

def_personality = "wh2_darkelf_early_hard";
hef_personality = "wh2_highelf_early_hard";
wef_personality = "wh_dlc05_wood_elves_default_main";

-- CAI personality to use for legendary difficulty
elseif difficulty_str == "legendary" then

def_personality = "wh2_darkelf_early_hard";
hef_personality = "wh2_highelf_early_hard";
wef_personality = "wh_dlc05_wood_elves_default_main";
end;

local faction_list = cm:model():world():faction_list();

for i = 0, faction_list:num_items() - 1 do
local faction = faction_list:item_at(i);
local faction_name = faction:name();
local faction_culture = faction:culture();

-- Checking whetether the faction exists and is alive
if faction:is_null_interface() == false and faction:is_dead() == false and faction:is_human() == false then

-- Dark Elves culture
if faction_culture == "wh2_main_def_dark_elves" then

-- Changing the CAI for all Dark Elf factions
cm:force_change_cai_faction_personality(faction_name, def_personality);
out("ELF: Changing CAI personality for " .. faction_name .. " to " .. def_personality .. " on " .. difficulty_str .. " difficulty");

-- High Elves culture
elseif faction_culture == "wh2_main_hef_high_elves" then

-- Changing the CAI for all High Elf factions
cm:force_change_cai_faction_personality(faction_name, hef_personality);
out("ELF: Changing CAI personality for " .. faction_name .. " to " .. hef_personality .. " on " .. difficulty_str .. " difficulty");

-- Wood Elves culture
elseif faction_culture == "wh_dlc05_wef_wood_elves" then

-- Changing the CAI for all Wood Elf factions
cm:force_change_cai_faction_personality(faction_name, wef_personality);
out("ELF: Changing CAI personality for " .. faction_name .. " to " .. wef_personality .. " on " .. difficulty_str .. " difficulty");
end;
end;
end;
end;
end;

cm:add_first_tick_callback(function() replace_cai_difficulty() end);</nowiki>

=== Spawning a Unique Agent ===

<nowiki>
--[[
Script by Aexrael Dex
Spawns a Unique Agent next to the starting lord of a specified faction
]]

local function add_unique_agent()

-- 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("unique_agent_enabled") == nil then

-- Starting agent setup
unique_agent_setup();
end;
end;

function unique_agent_setup()
-- Agent Details
local agent_details = {
faction_str = "wh2_dlc13_emp_the_huntmarshals_expedition", -- faction_key from factions
forename_key = "names_name_2147359013", -- forename_key from names
family_name_key = "names_name_1535812850", -- family_name_key from names
subtype_key = "wh2_dlc13_emp_hunter_jorek_grimm", -- agent subtype_key from agent_subtypes
art_set_key = "wh2_dlc13_art_set_emp_hunter_jorek_grimm_0", -- agent art_set_id from campaign_character_arts
unique_string = "wh2_dlc13_emp_hunter_jorek_grimm", -- unique agent string from unique_agents
saved_value = "unique_agent_enabled", -- saved_value string
trait = "wh2_dlc09_trait_benevolence" -- agent trait from character_traits
};

-- Monitor activated, listening for FactionTurnStart for The Huntmarshals Expedition
core:add_listener(
"unique_agent_setup",
"FactionTurnStart",
function(context)
return context:faction():name() == agent_details.faction_str;
end,
function(context)
-- Spawning Jorek as a unique agent next to Markus
local faction = cm:get_faction(agent_details.faction_str);
local faction_cqi = faction:command_queue_index();
local faction_leader_cqi = faction:faction_leader():command_queue_index();

cm:disable_event_feed_events(true, "wh_event_category_agent", "", "");
cm:spawn_unique_agent_at_character(
faction_cqi,
agent_details.unique_string,
faction_leader_cqi,
true
);
cm:callback(function()
cm:disable_event_feed_events(false, "wh_event_category_agent", "", "");
CampaignUI.ClearSelection();
end, 0.5);
out("UNIQ: Spawned Jorek next to Markus");

-- Looping through the character list for The Huntmarshals Expedition
local char_list = faction:character_list();

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);

-- Adding Joreks trait, replenishing AP and overriding the art set
if current_char:is_null_interface() == false and current_char:character_subtype_key() == agent_details.subtype_key then

-- Adding trait
cm:force_add_trait(char_str, agent_details.trait, false);
out("UNIQ: Adding " .. agent_details.trait .. " to Jorek");

-- Replenishing action points
cm:replenish_action_points(char_str);
out("UNIQ: Replenishing the action points of Jorek");

-- Failsafe for the random chance that the art_set doesn't apply properly
cm:add_unit_model_overrides(char_str, agent_details.art_set_key);
out("UNIQ: Adding unit model override for Jorek");
end;
end;

-- Setting saved value, so that the script doesn't run again when reloaded from a saved game
cm:set_saved_value(agent_details.saved_value, true);
out("UNIQ: Setting saved value " .. agent_details.saved_value);
end,
false
);
end;

cm:add_first_tick_callback(function() add_unique_agent() end);</nowiki>

Mods

2022-01-18T21:37:19Z

Fenriswolf: linked the two wrong links to the proper pages

A mod is any alteration to the base game, through [[modding]].

Mods are made up of a single .pack file, which contains all the changes for that mod, and a single .png file of the same name - which is just used as the thumbnail within Steam and the Total War Launcher.
== Finding Mods ==
Most mods that you will find can be discovered on the Steam Workshop page, for each Total War game.

* [https://steamcommunity.com/app/594570/workshop/ Total War: Warhammer 2 Steam Workshop]
* Etc.

Point of assistance here - you'll have a better time either Googling for the mods you're looking for (ie., "total war warhammer 2 greenskin units mods"), or searching for a collection on the Workshop. Steam Workshop is... a subpar searching service. Ironically.

== Installation ==
When you find a mod you like in the Steam Workshop, you simply press the "Subscribe" button - '''making sure to download all required items for that mod!''' - and let Steam download it in the background. Next time you load up the game, you will see it available in the launcher's mod manager. Simply tick the mod in the manager, and it will be enabled next time you press play!

Important note here: Don't faff around with [[Troubleshooting#How_to_Load_Order|load order]]. Mods are sorted alphanumerically by default, and modders are aware of the priorities needed between mods most of the time, when it comes to [[Tutorial:Submodding#WHAT_IS_A_SUBMOD.3F|submods]] or similar.

== Troubleshooting ==

If a mod doesn't appear to work or update, you can try to unsubscribe and re-subscribe, though in some instances this may not be enough and you may need to Clear the Steam Download Cache, see this [https://support.steampowered.com/kb_article.php?ref=3134-TIAL-4638 article]

See also: [[Troubleshooting]]

== Compatibility ==

Modding

2021-04-14T09:31:41Z

Fenriswolf: linked to the installing and using mods guide

Modding, or creating [[mods]], is the act of modifying the game files in order to cause changes or create new behavior within the game. There's a lot that can be done with modding - this page seeks to be a clear outline of what modding is, what you can and cannot mod, and other important high-level concepts.

If you're looking for [[Tutorial:Using Mods|using mods]], check that page.

And you can check the [[Tutorial:Main Page|modding tutorials]] page for a portal about various available, specific tutorials.

== What's a Mod ==
A mod - short for "Modification" - can be anything user-created that edits the game in a meaningful way.

In the Total War series, mods are composed of a single file - a .pack file - which contain all of the changes within that mod. Packs act like a .zip or .rar file, a compressed folder in a single file. Much of the vanilla game is composed of various CA-made pack files.

Packs can contain a lot of various pieces, such as:

* '''Data:''' One of the most-used parts of a mod is databasing. Total War uses database files, similar to spreadsheets, which can be used to change behavior and values, or add new objects to the game. This is used for much of the game, from units and their stats to the cost of buildings and much in between.
* '''Text:''' On top of that, text you see in the game - from the name of a lord to the flavour text of a skill - is done within packs, in .loc files. These files attach text to the database, and they can be used for translations as well!
* '''Assets:''' This is a wide topic - but much of the game can be edited through assets. Assets range from .png images scattered throughout the UI, to altered .dds files which are used on the various unit models in the game, to entirely new models or otherwise.
* '''Battle Maps:''' Battle maps are created through the Terry tool, from within the [[Assembly Kit]].
* '''Scripts:''' There's a layer of the game that can be interacted with through scripts (.lua files). Scripts power things such as characters getting experience, legendary lord defeat traits, and the Chaos Invasion - and much in between!

There's natural limitations to modding the game, since the game is written in a way that cannot be decompiled easily - meaning much of the game code and engine is unreadable and untouchable. That said, Creative Assembly does a comparatively excellent job at making sure much of the game is exposed to being modified!

== Getting Started ==
You've decided on a general mod idea you want to do, and you're ready to set aside some time to try, fail, try, fail, try and then inexplicably succeed the third time. This is the spot for you!

First thing's first, before you go on, you need to grab the [https://github.com/Frodo45127/rpfm/releases/latest Rusted Pack File Manager], by Frodo. It's the primary tool available to create a .pack file, edit it, and manipulate it in whatever way, and comes with a lot of excellent functionality.

Right after installing RPFM, you should decide on a folder on your computer that you'll store your mods. This'll be your primary directory for modding. For instance, I have S:/modding/ determined as my main spot on disk. Name it whatever you want, put it wherever you want.

Then, within RPFM, open the Preferences menu (through Ctrl+P, or PackFile -> Preferences), and begin to set up the necessary preferences within. Target all of the folders for all installed Total War games, targeting the folder where the .exe of the game is. Underneath, in "MyMod's Folder", fill in your new folder.
[[File:Screenshot 2021-01-31 205343.png|left|thumb|710x710px|Fill in your MyMod folder here!]]

Fill out whatever other preferences you may like, but most of this stuff you'll see through time. Keep "Allow Editing of CA PackFiles" to false, I prefer to have all of the checks valid on start, and of course the Use Dark Theme setting is an absolute must.

With RPFM, we can do an absolute load of modding. I recommend [[Setting up GitHub|using GitHub]] for version and source control - it's saved me several dozen times when I almost certainly would've lost an entire mod, or gotten two versions (ie. an update version and the retail version) mixed up.

You may also want to download the [[Assembly Kit]] for the game you're modding, as well as [https://www.microsoft.com/en-us/microsoft-365/excel Excel] or another spreadsheet program - it can come in hand a billion times over.

With all of our tools set up, we can get [[First Mod|started on our first mod]]!

== Guidelines ==
This is a list of hopefully helpful tips for modders - new or old.

* '''Start small, build up.''' One of the oldest tricks in the book is having a tremendously bloated idea, trying to make it all at once, getting overwhelmed, and then quitting. We've literally all done it. Instead of trying to build a pyramid from the bottom up, try to build a glacier from the top down, starting with a simpler idea and continuing it naturally.
* '''Ask for help.''' The Total War modding community, especially that around the Modding Den Discord, is a big help - you're not in this alone.

Tutorial:Using Mods

2021-03-31T22:14:59Z

Fenriswolf: Fixed formatting.

== Before we begin ==
This guide explains how you to use mods. It has nothing to do with the actual creating part of modding. The KMM parts of this guide are recommended but not strictly neccesary. But like Gromby aptly says:
[[File:USEKMM.jpg]]
This guide is written with steam in mind, if you are an epic games user go to the end of the guide to find out what you need to do different.

== Setting up KMM ==
=== Installing KMM ===
1) Download from: [https://github.com/Kaedrin/warhammer-mod-manager/releases/latest Kaedrin´s mod manager latest download]
2) Unzip the folder in your Documents directory OR your Desktop. ANYWHERE except the game directories or anything related to Steam.
3) Create a shortcut to Warhammer2MM.exe and put it on your Desktop
4) If you need to set the shortcut to admin mode, right click the shortcut, go to properties, click Advanced, and turn on "Run as Administrator"
=== Setting up the paths ===
* After you have installed it when you open it for the first time it will give you a popup about detecting your game paths. Just click accept and reopen KMM. KMM should already have detected all your TW games. You can check this by clicking on the "Game" header in KMM. The black names are the ones which it detected and you can choose. The grey names are the ones which would be possible but it either didn´t detect or you don´t own. KMM smells pirated TW games from miles away so if you pirated it it will also not work.
* When clicking on the "Options" header you can set the paths for Mod Backups if you want KMM to backup your mods for you, PFM (switch to RPFM pls if you still use PFM) and RPFM (Rusted Packfile Manager the tool with which most of us create our mods). You can also force KMM to try to detect new game paths.
== Downloading Mods ==
So downloading Mods is fairly simple. You begin by opening your steam client. Then you click on the "COMMUNITY" Header in your client (1). After this you should be seeing a tab with your last played games. If the TW game for which you want to download mods is not in that list then please click on the search bar to the right of the list and search for the game. Once you see the name of your game click on it(2). You are now in the community tab of the game. Now click on the "WORKSHOP" header in that Tab (3). Here´s a picture where I highlighted the different steps in case you didn´t understand what I was talking about: [[File:Downloading Mods.PNG]]
Now you search for the mods you want to use. Once you have found them you click on the subscribe button and Steam should start the download automatically.
== Using KMM ==
Here´s a picture so you can understand my description better:
[[File:Using KMM.PNG]]
=== NR1: Options ===
* "Use last profile" and "Highlight recent mods" are pretty self-explanatory and should in my opinion both be ticked.
* "Backup Mods" and "Choose Backup Location" are still self-explanatory. Click on "Choose Backup Location" to choose where your backup should be saved and check "Backup Mods" to actually enable the Backup function.
* "Choose PFM location" and "Choose RPFM location" is used to set the path to the respective manager. (Pls don´t use PFM thought instead use RPFM)
* "Detect Game Installations" is used to retrigger the game detection if you have a new TW game you want to use mods for.
* "Bypass CA launcher" does what it says when ticked and should always be ticked in my opinion.
* "Bypass Conflict Detection" should be ticked unless you have a real need for it. But mostly you won´t.
=== NR2 and 2*: Profiles ===
* You can make a new profile by enabling the mods you want in it and then naming it in the text field (2*) and click save and you have your new profile.
* You can export your currently open profile via the "Profile" header (2). It will be saved as a txt file in the location you choose.
* You can import a profile if you have the txt file for it. You do this via the "Profile" header (2). It will automatically only enable the mods you are subbed to and are in that profile and disable all others.
=== NR3: Game ===
* You can see all games supported by KMM (grey names) and the ones which are supported and KMM detected (black names) when you click on the "Game" header.
=== NR4: Tips ===
* Here you see some good tips and info for using KMM
=== NR5: Version ===
* You can see the version you use in the top row and the latest version available under the headers. Make sure to always use the newest version.
=== NR6: Number of Mods ===
* You can see how many mods you have enabled in the top, left of the tips and info section.
* You can see the number of movie mods you have over the start button. Movie mods are always active regardless of if you activate them or not. So be aware of that. You can see which mods are movie mods by sorting via the "type column".
* You enable mods by checking the small box left of their name.
=== NR7: Launching and Refreshing ===
* The refresh button over the launch button is used to refresh KMM if you downloaded any mods while KMM was open so KMM becomes aware of the new mods.
* You launch the game by clicking on the launch button.
== Enabling mods (CA/Vanilla Launcher) ==
So you have succesfully downloaded a mod. Congratz! But you have decided against using KMM. Well it´s not my part to judge...
You enable mods by starting your game like you normally do but before you click on the play button inside of the TW launcher you click on the "Mod Manager" header on the left right next to the "Game" and "Shop" header.
Then you should be in the CA mod manager. There you search through the list of mods and click on the grey bar on their left to enable them. They should then turn green. Once you have enabled all the mods you want to use you click on the big play button in the upper right. You now get a popup that lists all enabled mods. Look through them if you forgot to enable some and then accept the popup. Here´s another picture to simplify:
[[File:Enabling Mods.PNG]] Congrats! You now succesfully activated a mod!
== Good Practices ==
* Don´t change Loadorder! Only do this if you are aware of what you are doing there and even then only do this if you have a good reason!
* If you have issues with mods try to fix them yourself first (I recommend Cataph´s excellent guide: [[Troubleshooting|Troubleshooting Guide]] ) and only if you have confirmed it is a problem with that particular mod contact the author. Most of us prefer Discord but Steam works as well.
* Don´t be obnoxious. Almost all of us are doing Modding as a hobby and not as a job. So don´t spam "UPDATE PLS" for example. There might be a very good reason why we didn´t update our mod yet or we just didn´t have time yet.
== Differences if you are using Epic Games instead of Steam ==
I have no idea as I don´t own a TW Game on Epic. But if you do and know what´s different for epic games then please fill in this section.

I’ll add more information later if people have questions or I forgot anything.

File:Using KMM.PNG

2021-03-31T22:13:17Z

Fenriswolf: Fenriswolf uploaded a new version of File:Using KMM.PNG

File uploaded with MsUpload

File:USEKMM.jpg

2021-03-31T22:11:01Z

Fenriswolf: File uploaded with MsUpload

File uploaded with MsUpload

Tutorial:Custom Lords & Heroes

2021-03-31T21:48:42Z

Fenriswolf: Missed one link

=== By Nanu ===

=== Contents ===

* Creating a Character
** agent_subtypes
** agent_uniforms
** campaign_character_art_sets
** campaign_character_arts
** character_skill_node_sets_tables
** faction_agent_permitted_subtypes
* Agent Actions
** agent_actions_tables
* Legendary Lords and Heroes

==== Setup ====
This guide assumes you have created the unit for you custom hero/lord, see [https://steamcommunity.com/sharedfiles/filedetails/?id=1694945483 Cryswar's Unit Guide] if you haven't yet.

You should also have [https://github.com/Frodo45127/rpfm/releases Rusted Pack File Manager] (RPFM). It's free, it's easy to use, and it's well maintained.

Below is a list of tables, localization files, and other resources that are required to add a new agent to the game, as well as a few optional ones.

Required

* Tables
** agent_subtypes
** agent_uniforms
** campaign_character_art_sets
** campaign_character_arts
** character_skill_node_sets
** faction_agent_permitted_subtypes
* Localizations
** agent_subtypes.loc
* [https://steamcommunity.com/sharedfiles/filedetails/?id=1194811468 Porthole Process]

Optional

* Tables
** agent_actions
** effect_bonus_value_agent_action_record_junctions_tables
** character_skill_level_to_effects_junctions_tables
** character_skill_nodes_tables
** names
* Localizations
** names.loc
* Lua script to spawn your character

Now I can drone on about the tables and whats in them or we can build a mod together. Lets do the latter. We're going to make a mod that adds new characters to the game.

So what kind of characters should we mod into the game? What kind of characters does Total War Warhammer II need?

How about a Chaos Sorcerer of Life, and a Chaos Sorcerer Lord of Life. Maybe Archaon had a change of heart and wants to heal the world.

We're going to ignore the unit tables, if you want to build this mod along with this guide then go ahead and set up the unit tables now. [https://steamcommunity.com/sharedfiles/filedetails/?id=1694945483 This guide] will help you set everything up

Great! Now that we have our units ready lets walk through the tables we need to create our tree hugging Champions of Chaos. I have provided the tables needed in this guide, but some are too large to fit on the page. You'll need to zoom out (left ctrl + mouse wheel) to see them fully.

One more thing, [https://steamcommunity.com/sharedfiles/filedetails/?id=2137707555 this is our completed mod], you can download it and use it to follow along if you'd like.
----

=== Creating the Character ===

==== agent_subtypes ====
Any character or lord on the campaign map or embedded into an army is an agent. The agent_subtypes table contains basic information about this specific subtype of agent.

Here's the agent_subtypes table for our new chaos characters

I know, theres a lot, but don't worry! Its not as hard as it looks and most of it is self explanatory

* Key
** Key is well, the key of our agent subtype. This is a unique key that will be used to reference our agent from the db or scripts. This must be a unique key and if possible should match the main_unit key for your agent.
* Auto Generate
** Whether or not the game should automatically generate this character and add them to the character pool. Leave this unchecked for unique characters like Legendary Lords. Names will be generated from the factions name list. Starting traits have to be added to a list for each subtype. More on that later. For our characters, we are going to leave this checked, since we want the game to make generic versions of these characters
* Is Caster
** This just determines whether or not this character can use casting items.
* Small Icon
** The icon you'll see on the campaign map for this character. Lords have this icon overridden so you can leave it blank for them.
* Associated Unit Override
** The main_unit key associated with this character. You don't need a new subtype for each mount, only the base unit is needed here.
* Audio Voiceover Actor Group
** The voice that this character has on the campaign map. Battle voice actor is determined in main_units (yes, they can be different).
* Show in Ui
** Whether or not this character shows up in the recruitment panel. Set to false for Legendary Heroes like Cylostra's Damned Paladin or Wulfhart's unique hereos.
* Cap
** This is only used for Gotrek, Felix, Lord Kroak, and Henri le Massif. As far as I know it isn't needed even for Legendary Lords or unique heroes. Leave this as -1.
* Has Female Name
** Self Explanatory
* Can Gain Xp
** Self Explanatory
* Loyalty is Applicable
** This doesn't add your lord to the loyalty system, it only shows the loyalty icon above their banner and in their details panel. Loyalty is scripted, you must add your lords to the loyalty scripts to add them to the loyalty system
* Contributes to Agent Cap
** Whether or not this subtype takes up an agent slot. I set this to false for my unique Heroes, but you can leave it as true if you want. This should always be true for Lords.
* Recruitment Category
** As of the Warden and the Paunch, Lords now are separated into different groups like Heroes. This value determines which group your lord should be sorted into. Leave this blank for Heroes
* Magic Lore
** Used only for sorting Lords into categories under their respective Recruitment Category. Leave this blank for Heroes
* Audio Vo Culture Override
** Only Grom and the River Troll Hag use this. Just leave it blank

----

==== agent_uniforms ====
This one is simple, and you should have already done this when you went through the [https://steamcommunity.com/sharedfiles/filedetails/?id=1194811468 porthole process]. I won't go through it since this its pretty simple, just reference the variant key for your subtype (or for this variation, you need a uniform for each variant unless you want this hero type to all look the same).
----

==== campaign_character_art_sets ====
This table is one of two that determine your agent's campaign variant.

* Art Set Id
** Unique ID for your character Art Set. This is needed for every variation of your subtype. Most vanilla agents have 2-5 different art sets (and subsequent uniforms/portholes). Our characters only have one each to make things easy.
* Is Custom
** Leave this false. Only a few unique characters like Kemmler and Mannfred use this and idk why
* Agent Type
** The agent type your subtype belongs to. Lords are all generals, heroes can be wizards, champions, spies, dignitaries, and engineers. There are others but they're deprecated
* Faction
** I'm pretty sure this is how you limit which faction this art set applies to, Lokhir is the only one I'm aware of that uses this. Best to leave this blank
* Culture
** Same as above, just follow a vanilla equivalent
* Subculture
** Again, same as above. Chaos Lords and Heroes use this column, so I did too. When in doubt do what CA does
* Is Male
** Leave this checked. Yes, even if your character is a girl.
* Agent Subtype
** Your agent_subtype key
* Campaign Map Scale
** Leave as 1

----

==== campaign_character_arts ====

* Art Set Id
** Same as your art set Id from the above table
* Level
** Leave this as 0
* Season
** Leave this as none
* Age
** Leave this as 0
* Portrait
** Leave this blank
* Uniform
** The agent_uniform this character art uses
* Card
** Leave blank
* Info
** Leave blank
* Sea Uniform
** The ship you see on the campaign map when this agent embarks onto the water
* Navy Uniform
** Deprecated. Use the faction's default lord Navy Uniform
* Land Animation
** The animation your character uses on the campaign map. Must be a campaign animation, battle animations don't work here.
* Sea Animation
** The animation your ship uses on the water.
* Navy Animation
** again, deprecated, copy the vanilla Lord default value
* Id
** Unique ID for this character art. This must be a unique number.
* Religion
** Leave blank
* Land Animation Vfx Filter
** Leave as 0
* Sea Animation Vfx Filter
** Leave as 0
* Navy Animation Vfx Filter
** Leave as 0

----

==== character_skill_node_sets_tables ====
This table connects your character skill node set to your subtype. Without this table, your character won't have any skills to use when they level up. I won't go through the basics of skills in this guide, [https://steamcommunity.com/sharedfiles/filedetails/?id=1696051257 there already exists a guide for it], but you will need this to fully flesh out your characters so I've added it.

* Key
** Unique Key for this node set
* Faction Key
** Leave blank
* Campaign Key
** Leave Blank
* Agent Key
** The Agent type for you subtype. Yes, you have to specify it again. This isn't even the last time either.
* Subculture
** Leave Blank
* For Army
** Leave unchecked
* For Navy
** Leave unchecked
* Agent Subtype
** This will add this character node set to your agent subtype. All characters with this subtype will have the same skill node set. If you want your characters to have different skill node sets you need to make new subtypes

----

==== faction_agent_permitted_subtypes ====
This mess of a table is what adds your agent subtype to the faction of your choice. You have to add your subtype to every faction that will have access to the subtype.

* Faction
** The faction that will now have access to this agent subtype
* Agent
** Yes, you have to specify this again. No, I don't know why
* Subtype
** Your agent subtype

----

==== agent_subtypes.loc ====
You should be familiar with loc files by now, this just specifies the name and description of your agent subtypes.
----And thats it! With those tables filled out, you've done everything you need to turn your unit into a recruitable character! Assuming you have your unit tables finished, you can now go into campaign and recruit your new Chaos Sorcerer Lord of Life.

If it's crashing or your characters aren't showing up as recruitable, check that you filled out everything right, or [https://steamcommunity.com/sharedfiles/filedetails/?id=2137707555 use the example mod as a comparison].
----

=== Adding Agent Actions ===
But wait! What about our Chaos Sorcerer's campaign actions? How can we get our new campaign hero to assault units or assassinate a character?

Well, the campaign actions are added via skills, and we can just add a skill that CA already defined for us to our characters skill node set. But maybe we want our character to be a little more unique?

Lets give them a different set of abilities, we'll need to create a new skill, which you can do by following [https://steamcommunity.com/sharedfiles/filedetails/?id=1696051257 this guide]. After you made a new skill and added it to the skill node set, lets add some agent actions to it in the character_skill_level_to_effects_junctions table:

This is a copy of the vanilla wh2_main_skill_all_dummy_agent_actions_chs_sorcerer skill, but we want to make some changes, so lets replace the passive wh2_main_effect_agent_action_enable_wizard_hinder_settlement_steal_technology, which give our hero the ability to boost technolofy by attacking a settlement, and replace it with wh2_main_effect_agent_action_enable_wizard_hinder_settlement_damage_walls, which lets him damage the walls instead:

Great! Now we have a hero who has a different set of campaign actions. Keep in mind you must use effects that apply to your agent type, if you want to add an agent action that doesn't exist already, you must make the agent action and effect to apply it. Lets go ahead and make a new agent action for the Chaos Sorcerer of Life. We'll give him the ability to assassinate, something normal wizards can't do in the base game. Here are the tables you'll need:

* agent_actions
* effect_bonus_value_agent_action_record_junctions_tables

I'm going to skip over the effect tables, you can make a new empty effect using [https://steamcommunity.com/sharedfiles/filedetails/?id=1761177338 this guide] if you want to follow along, otherwise, I'll assume you have your effect ready.

==== agent_actions ====
This table is very convoluted and particularly finicky, you'll want to start with an agent action that already exists to avoid making mistakes. Lets start with the Exalted Hero's assassinate ability, defined as wh2_main_agent_action_champion_hinder_agent_assassinate

in the agent_actions table.

We're not going to change much here, just the Agent and the Unique Id. We'll copy this row from the CA data.pack into our mod, change Agent to wizard and Unique Id to chs_chaos_sorcerer_life_assassinate

Now we can add the agent action to the effect_bonus_value_agent_action_record_junctions_table

And finally add our effect to the chs_chaos_sorcerer_life_agent_actions skill we made

And that's it! We now have a custom hero subtype that has a unique set of campaign actions!

=== Legendary Lords and Heroes ===
Making Legendary Lords and Heroes is simple, plus you've already done most of the legwork. A guide on how to name them and spawn them on the campaign map is available [https://steamcommunity.com/sharedfiles/filedetails/?id=1695928423 here].
[[Category:Unfinished]]
[[Category:Outdated]]
[[Category:Warhammer 2]]

Tutorial:Custom Lords & Heroes

2021-03-29T18:51:41Z

Fenriswolf: I changed the links to steam links since the pages where they linked originally don´t exist anymore

=== By Nanu ===

=== Contents ===

* Creating a Character
** agent_subtypes
** agent_uniforms
** campaign_character_art_sets
** campaign_character_arts
** character_skill_node_sets_tables
** faction_agent_permitted_subtypes
* Agent Actions
** agent_actions_tables
* Legendary Lords and Heroes

==== Setup ====
This guide assumes you have created the unit for you custom hero/lord, see [https://steamcommunity.com/sharedfiles/filedetails/?id=1694945483 Cryswar's Unit Guide] if you haven't yet.

You should also have [https://github.com/Frodo45127/rpfm/releases Rusted Pack File Manager] (RPFM). It's free, it's easy to use, and it's well maintained.

Below is a list of tables, localization files, and other resources that are required to add a new agent to the game, as well as a few optional ones.

Required

* Tables
** agent_subtypes
** agent_uniforms
** campaign_character_art_sets
** campaign_character_arts
** character_skill_node_sets
** faction_agent_permitted_subtypes
* Localizations
** agent_subtypes.loc
* [https://steamcommunity.com/sharedfiles/filedetails/?id=1194811468 Porthole Process]

Optional

* Tables
** agent_actions
** effect_bonus_value_agent_action_record_junctions_tables
** character_skill_level_to_effects_junctions_tables
** character_skill_nodes_tables
** names
* Localizations
** names.loc
* Lua script to spawn your character

Now I can drone on about the tables and whats in them or we can build a mod together. Lets do the latter. We're going to make a mod that adds new characters to the game.

So what kind of characters should we mod into the game? What kind of characters does Total War Warhammer II need?

How about a Chaos Sorcerer of Life, and a Chaos Sorcerer Lord of Life. Maybe Archaon had a change of heart and wants to heal the world.

We're going to ignore the unit tables, if you want to build this mod along with this guide then go ahead and set up the unit tables now. [https://steamcommunity.com/sharedfiles/filedetails/?id=1694945483 This guide] will help you set everything up

Great! Now that we have our units ready lets walk through the tables we need to create our tree hugging Champions of Chaos. I have provided the tables needed in this guide, but some are too large to fit on the page. You'll need to zoom out (left ctrl + mouse wheel) to see them fully.

One more thing, [https://steamcommunity.com/sharedfiles/filedetails/?id=2137707555 this is our completed mod], you can download it and use it to follow along if you'd like.
----

=== Creating the Character ===

==== agent_subtypes ====
Any character or lord on the campaign map or embedded into an army is an agent. The agent_subtypes table contains basic information about this specific subtype of agent.

Here's the agent_subtypes table for our new chaos characters

I know, theres a lot, but don't worry! Its not as hard as it looks and most of it is self explanatory

* Key
** Key is well, the key of our agent subtype. This is a unique key that will be used to reference our agent from the db or scripts. This must be a unique key and if possible should match the main_unit key for your agent.
* Auto Generate
** Whether or not the game should automatically generate this character and add them to the character pool. Leave this unchecked for unique characters like Legendary Lords. Names will be generated from the factions name list. Starting traits have to be added to a list for each subtype. More on that later. For our characters, we are going to leave this checked, since we want the game to make generic versions of these characters
* Is Caster
** This just determines whether or not this character can use casting items.
* Small Icon
** The icon you'll see on the campaign map for this character. Lords have this icon overridden so you can leave it blank for them.
* Associated Unit Override
** The main_unit key associated with this character. You don't need a new subtype for each mount, only the base unit is needed here.
* Audio Voiceover Actor Group
** The voice that this character has on the campaign map. Battle voice actor is determined in main_units (yes, they can be different).
* Show in Ui
** Whether or not this character shows up in the recruitment panel. Set to false for Legendary Heroes like Cylostra's Damned Paladin or Wulfhart's unique hereos.
* Cap
** This is only used for Gotrek, Felix, Lord Kroak, and Henri le Massif. As far as I know it isn't needed even for Legendary Lords or unique heroes. Leave this as -1.
* Has Female Name
** Self Explanatory
* Can Gain Xp
** Self Explanatory
* Loyalty is Applicable
** This doesn't add your lord to the loyalty system, it only shows the loyalty icon above their banner and in their details panel. Loyalty is scripted, you must add your lords to the loyalty scripts to add them to the loyalty system
* Contributes to Agent Cap
** Whether or not this subtype takes up an agent slot. I set this to false for my unique Heroes, but you can leave it as true if you want. This should always be true for Lords.
* Recruitment Category
** As of the Warden and the Paunch, Lords now are separated into different groups like Heroes. This value determines which group your lord should be sorted into. Leave this blank for Heroes
* Magic Lore
** Used only for sorting Lords into categories under their respective Recruitment Category. Leave this blank for Heroes
* Audio Vo Culture Override
** Only Grom and the River Troll Hag use this. Just leave it blank

----

==== agent_uniforms ====
This one is simple, and you should have already done this when you went through the [https://steamcommunity.com/sharedfiles/filedetails/?id=1194811468 porthole process]. I won't go through it since this its pretty simple, just reference the variant key for your subtype (or for this variation, you need a uniform for each variant unless you want this hero type to all look the same).
----

==== campaign_character_art_sets ====
This table is one of two that determine your agent's campaign variant.

* Art Set Id
** Unique ID for your character Art Set. This is needed for every variation of your subtype. Most vanilla agents have 2-5 different art sets (and subsequent uniforms/portholes). Our characters only have one each to make things easy.
* Is Custom
** Leave this false. Only a few unique characters like Kemmler and Mannfred use this and idk why
* Agent Type
** The agent type your subtype belongs to. Lords are all generals, heroes can be wizards, champions, spies, dignitaries, and engineers. There are others but they're deprecated
* Faction
** I'm pretty sure this is how you limit which faction this art set applies to, Lokhir is the only one I'm aware of that uses this. Best to leave this blank
* Culture
** Same as above, just follow a vanilla equivalent
* Subculture
** Again, same as above. Chaos Lords and Heroes use this column, so I did too. When in doubt do what CA does
* Is Male
** Leave this checked. Yes, even if your character is a girl.
* Agent Subtype
** Your agent_subtype key
* Campaign Map Scale
** Leave as 1

----

==== campaign_character_arts ====

* Art Set Id
** Same as your art set Id from the above table
* Level
** Leave this as 0
* Season
** Leave this as none
* Age
** Leave this as 0
* Portrait
** Leave this blank
* Uniform
** The agent_uniform this character art uses
* Card
** Leave blank
* Info
** Leave blank
* Sea Uniform
** The ship you see on the campaign map when this agent embarks onto the water
* Navy Uniform
** Deprecated. Use the faction's default lord Navy Uniform
* Land Animation
** The animation your character uses on the campaign map. Must be a campaign animation, battle animations don't work here.
* Sea Animation
** The animation your ship uses on the water.
* Navy Animation
** again, deprecated, copy the vanilla Lord default value
* Id
** Unique ID for this character art. This must be a unique number.
* Religion
** Leave blank
* Land Animation Vfx Filter
** Leave as 0
* Sea Animation Vfx Filter
** Leave as 0
* Navy Animation Vfx Filter
** Leave as 0

----

==== character_skill_node_sets_tables ====
This table connects your character skill node set to your subtype. Without this table, your character won't have any skills to use when they level up. I won't go through the basics of skills in this guide, [[Tutorial:Custom Skills, Items, and Effects|there already exists a guide for that]], but you will need this to fully flesh out your characters so I've added it.

* Key
** Unique Key for this node set
* Faction Key
** Leave blank
* Campaign Key
** Leave Blank
* Agent Key
** The Agent type for you subtype. Yes, you have to specify it again. This isn't even the last time either.
* Subculture
** Leave Blank
* For Army
** Leave unchecked
* For Navy
** Leave unchecked
* Agent Subtype
** This will add this character node set to your agent subtype. All characters with this subtype will have the same skill node set. If you want your characters to have different skill node sets you need to make new subtypes

----

==== faction_agent_permitted_subtypes ====
This mess of a table is what adds your agent subtype to the faction of your choice. You have to add your subtype to every faction that will have access to the subtype.

* Faction
** The faction that will now have access to this agent subtype
* Agent
** Yes, you have to specify this again. No, I don't know why
* Subtype
** Your agent subtype

----

==== agent_subtypes.loc ====
You should be familiar with loc files by now, this just specifies the name and description of your agent subtypes.
----And thats it! With those tables filled out, you've done everything you need to turn your unit into a recruitable character! Assuming you have your unit tables finished, you can now go into campaign and recruit your new Chaos Sorcerer Lord of Life.

If it's crashing or your characters aren't showing up as recruitable, check that you filled out everything right, or [https://steamcommunity.com/sharedfiles/filedetails/?id=2137707555 use the example mod as a comparison].
----

=== Adding Agent Actions ===
But wait! What about our Chaos Sorcerer's campaign actions? How can we get our new campaign hero to assault units or assassinate a character?

Well, the campaign actions are added via skills, and we can just add a skill that CA already defined for us to our characters skill node set. But maybe we want our character to be a little more unique?

Lets give them a different set of abilities, we'll need to create a new skill, which you can do by following [https://steamcommunity.com/sharedfiles/filedetails/?id=1696051257 this guide]. After you made a new skill and added it to the skill node set, lets add some agent actions to it in the character_skill_level_to_effects_junctions table:

This is a copy of the vanilla wh2_main_skill_all_dummy_agent_actions_chs_sorcerer skill, but we want to make some changes, so lets replace the passive wh2_main_effect_agent_action_enable_wizard_hinder_settlement_steal_technology, which give our hero the ability to boost technolofy by attacking a settlement, and replace it with wh2_main_effect_agent_action_enable_wizard_hinder_settlement_damage_walls, which lets him damage the walls instead:

Great! Now we have a hero who has a different set of campaign actions. Keep in mind you must use effects that apply to your agent type, if you want to add an agent action that doesn't exist already, you must make the agent action and effect to apply it. Lets go ahead and make a new agent action for the Chaos Sorcerer of Life. We'll give him the ability to assassinate, something normal wizards can't do in the base game. Here are the tables you'll need:

* agent_actions
* effect_bonus_value_agent_action_record_junctions_tables

I'm going to skip over the effect tables, you can make a new empty effect using [https://steamcommunity.com/sharedfiles/filedetails/?id=1761177338 this guide] if you want to follow along, otherwise, I'll assume you have your effect ready.

==== agent_actions ====
This table is very convoluted and particularly finicky, you'll want to start with an agent action that already exists to avoid making mistakes. Lets start with the Exalted Hero's assassinate ability, defined as wh2_main_agent_action_champion_hinder_agent_assassinate

in the agent_actions table.

We're not going to change much here, just the Agent and the Unique Id. We'll copy this row from the CA data.pack into our mod, change Agent to wizard and Unique Id to chs_chaos_sorcerer_life_assassinate

Now we can add the agent action to the effect_bonus_value_agent_action_record_junctions_table

And finally add our effect to the chs_chaos_sorcerer_life_agent_actions skill we made

And that's it! We now have a custom hero subtype that has a unique set of campaign actions!

=== Legendary Lords and Heroes ===
Making Legendary Lords and Heroes is simple, plus you've already done most of the legwork. A guide on how to name them and spawn them on the campaign map is available [https://steamcommunity.com/sharedfiles/filedetails/?id=1695928423 here].
[[Category:Unfinished]]
[[Category:Outdated]]
[[Category:Warhammer 2]]

Example Scripts

2021-03-29T17:44:17Z

Fenriswolf: Set a space between the [[ of the example as it was getting picked up as a link and not as the symbols (as it should since you want to show how to comment in portuguese moon)

A list of example scripts that can easily be copied, edited and then put into a [[Mods|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 logging|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 ===

<nowiki>
--[[
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);</nowiki>

=== Adding RoRs to mercenary pool ===

<nowiki>--[[
Script by Aexrael Dex
Adds custom Regiments of Reknown to specified factions
]]

local function add_custom_ror()

-- 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_key = "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 = true},
{faction_key = "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 = true}
};

-- Loop for the table above
for i = 1, #cror_list do
local faction_name = cror_list[i].faction_key; -- Faction whose pool the unit(s) should be added to
local faction = cm:get_faction(faction_name); -- FACTION_SCRIPT_INTERFACE
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, unit_key, unit_count, rcp, munits, murpt, xplevel, frr, srr, trr, replen);

-- Debug message for log
out("CROR: adding the custom ror unit " .. unit_key .. " to " .. faction_name);
end;

-- 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);
end;
end;

cm:add_first_tick_callback(function() add_custom_ror() end);</nowiki>

=== Replacing Starting Armies ===

<nowiki>--[[
Script by Aexrael Dex
Replaces the starting units for specified starting Lords
]]

local function army_tweaks()

-- Checking whether it's a new game, we don't want to replace armies in the middle of a campaign
if cm:is_new_game() then

-- Creating a table with entries for the various starting Lords, their Faction key from Factions table, subtype key from agent_subtypes, Forename from names table and Unit List with keys from Main Units
local starting_army = {
-- Vlad, Carsteins
{faction_key = "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_key = "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, #starting_army do
local faction_name = starting_army[i].faction_key;
local faction = cm:get_faction(faction_name);
local char_list = faction:character_list();
local general_subtype = starting_army[i].subtype;
local general_forename = starting_army[i].forename;
local unit_list = starting_army[i].units;

for j = 0, char_list:num_items() - 1 do
local current_char = char_list:item_at(j);
local char_str = cm:char_lookup_str(current_char);

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

-- Removing all existing units from the General
cm:remove_all_units_from_general(current_char);
out("ARMY: Removing starting units from " .. general_subtype .. " with forename " .. general_forename);

for k = 1, #unit_list do
local unit = unit_list[k];

-- Granting new units to the General
cm:grant_unit_to_character(char_str, unit);
out("ARMY: Adding new starting units to " .. general_subtype .. " with forename " .. general_forename);
end;
end;
end;
end;
end;
end;

cm:add_first_tick_callback(function() army_tweaks() end);</nowiki>

=== Changing CAI based on campaign difficulty ===

<nowiki>--[[
Script by Aexrael Dex
Replaces the Campaign AI Personality for specific factions depending on the chosen campaign difficulty level
]]

local function replace_cai_difficulty()
if cm:is_new_game() == true then
local difficulty_str = cm:get_difficulty(true);
local def_personality = "";
local hef_personality = "";
local wef_personality = "";

-- CAI personality to use for easy difficulty
if difficulty_str == "easy" then

def_personality = "wh2_darkelf_early_easy";
hef_personality = "wh2_highelf_early_easy";
wef_personality = "wh_dlc05_wood_elves_default_main";

-- CAI personality to use for normal difficulty
elseif difficulty_str == "normal" then

def_personality = "wh2_darkelf_early";
hef_personality = "wh2_highelf_early";
wef_personality = "wh_dlc05_wood_elves_default_main";

-- CAI personality to use for hard difficulty
elseif difficulty_str == "hard" then

def_personality = "wh2_darkelf_early_hard";
hef_personality = "wh2_highelf_early_hard";
wef_personality = "wh_dlc05_wood_elves_default_main";

-- CAI personality to use for very hard difficulty
elseif difficulty_str == "very hard" then

def_personality = "wh2_darkelf_early_hard";
hef_personality = "wh2_highelf_early_hard";
wef_personality = "wh_dlc05_wood_elves_default_main";

-- CAI personality to use for legendary difficulty
elseif difficulty_str == "legendary" then

def_personality = "wh2_darkelf_early_hard";
hef_personality = "wh2_highelf_early_hard";
wef_personality = "wh_dlc05_wood_elves_default_main";
end;

local faction_list = cm:model():world():faction_list();

for i = 0, faction_list:num_items() - 1 do
local faction = faction_list:item_at(i);
local faction_name = faction:name();
local faction_culture = faction:culture();

-- Checking whetether the faction exists and is alive
if faction:is_null_interface() == false and faction:is_dead() == false and faction:is_human() == false then

-- Dark Elves culture
if faction_culture == "wh2_main_def_dark_elves" then

-- Changing the CAI for all Dark Elf factions
cm:force_change_cai_faction_personality(faction_name, def_personality);
out("ELF: Changing CAI personality for " .. faction_name .. " to " .. def_personality .. " on " .. difficulty_str .. " difficulty");

-- High Elves culture
elseif faction_culture == "wh2_main_hef_high_elves" then

-- Changing the CAI for all High Elf factions
cm:force_change_cai_faction_personality(faction_name, hef_personality);
out("ELF: Changing CAI personality for " .. faction_name .. " to " .. hef_personality .. " on " .. difficulty_str .. " difficulty");

-- Wood Elves culture
elseif faction_culture == "wh_dlc05_wef_wood_elves" then

-- Changing the CAI for all Wood Elf factions
cm:force_change_cai_faction_personality(faction_name, wef_personality);
out("ELF: Changing CAI personality for " .. faction_name .. " to " .. wef_personality .. " on " .. difficulty_str .. " difficulty");
end;
end;
end;
end;
end;

cm:add_first_tick_callback(function() replace_cai_difficulty() end);</nowiki>

=== Spawning a Unique Agent ===

<nowiki>
--[[
Script by Aexrael Dex
Spawns a Unique Agent next to the starting lord of a specified faction
]]

local function add_unique_agent()

-- 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("unique_agent_enabled") == nil then

-- Starting agent setup
unique_agent_setup();
end;
end;

function unique_agent_setup()
-- Agent Details
local agent_details = {
faction_str = "wh2_dlc13_emp_the_huntmarshals_expedition", -- faction_key from factions
forename_key = "names_name_2147359013", -- forename_key from names
family_name_key = "names_name_1535812850", -- family_name_key from names
subtype_key = "wh2_dlc13_emp_hunter_jorek_grimm", -- agent subtype_key from agent_subtypes
art_set_key = "wh2_dlc13_art_set_emp_hunter_jorek_grimm_0", -- agent art_set_id from campaign_character_arts
unique_string = "wh2_dlc13_emp_hunter_jorek_grimm", -- unique agent string from unique_agents
saved_value = "unique_agent_enabled", -- saved_value string
trait = "wh2_dlc09_trait_benevolence" -- agent trait from character_traits
};

-- Monitor activated, listening for FactionTurnStart for The Huntmarshals Expedition
core:add_listener(
"unique_agent_setup",
"FactionTurnStart",
function(context)
return context:faction():name() == agent_details.faction_str;
end,
function(context)
-- Spawning Jorek as a unique agent next to Markus
local faction = cm:get_faction(agent_details.faction_str);
local faction_cqi = faction:command_queue_index();
local faction_leader_cqi = faction:faction_leader():command_queue_index();

cm:disable_event_feed_events(true, "wh_event_category_agent", "", "");
cm:spawn_unique_agent_at_character(
faction_cqi,
agent_details.unique_string,
faction_leader_cqi,
true
);
cm:callback(function()
cm:disable_event_feed_events(false, "wh_event_category_agent", "", "");
CampaignUI.ClearSelection();
end, 0.5);
out("UNIQ: Spawned Jorek next to Markus");

-- Looping through the character list for The Huntmarshals Expedition
local char_list = faction:character_list();

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);

-- Adding Joreks trait, replenishing AP and overriding the art set
if current_char:is_null_interface() == false and current_char:character_subtype_key() == agent_details.subtype_key then

-- Adding trait
cm:force_add_trait(char_str, agent_details.trait, false);
out("UNIQ: Adding " .. agent_details.trait .. " to Jorek");

-- Replenishing action points
cm:replenish_action_points(char_str);
out("UNIQ: Replenishing the action points of Jorek");

-- Failsafe for the random chance that the art_set doesn't apply properly
cm:add_unit_model_overrides(char_str, agent_details.art_set_key);
out("UNIQ: Adding unit model override for Jorek");
end;
end;

-- Setting saved value, so that the script doesn't run again when reloaded from a saved game
cm:set_saved_value(agent_details.saved_value, true);
out("UNIQ: Setting saved value " .. agent_details.saved_value);
end,
false
);
end;

cm:add_first_tick_callback(function() add_unique_agent() end);</nowiki>

Tutorial:Using Mods

2021-03-29T12:59:01Z

Fenriswolf: Finished the guide. I am not sure if my pictures and links work but we will see.

=== Before we begin ===
This guide explains how you to use mods. It has nothing to do with the actual creating part of modding. The KMM parts of this guide are recommended but not strictly neccesary. But like Gromby aptly says: https://media.discordapp.net/attachments/373745291289034765/569917924278796318/USEKMM.jpg?width=500&height=373 This guide is written with steam in mind, if you are an epic games user go to the end of the guide to find out what you need to do different.

=== Setting up KMM ===
== Installing KMM ==
1) Download from: [https://github.com/Kaedrin/warhammer-mod-manager/releases/latest Kaedrin´s mod manager latest download]
2) Unzip the folder in your Documents directory OR your Desktop. ANYWHERE except the game directories or anything related to Steam.
3) Create a shortcut to Warhammer2MM.exe and put it on your Desktop
4) If you need to set the shortcut to admin mode, right click the shortcut, go to properties, click Advanced, and turn on "Run as Administrator"
== Setting up the paths ==
* After you have installed it when you open it for the first time it will give you a popup about detecting your game paths. Just click accept and reopen KMM. KMM should already have detected all your TW games. You can check this by clicking on the "Game" header in KMM. The black names are the ones which it detected and you can choose. The grey names are the ones which would be possible but it either didn´t detect or you don´t own. KMM smells pirated TW games from miles away so if you pirated it it will also not work.
* When clicking on the "Options" header you can set the paths for Mod Backups if you want KMM to backup your mods for you, PFM (switch to RPFM pls if you still use PFM) and RPFM (Rusted Packfile Manager the tool with which most of us create our mods). You can also force KMM to try to detect new game paths.
=== Downloading Mods ===
So downloading Mods is fairly simple. You begin by opening your steam client. Then you click on the "COMMUNITY" Header in your client. After this you should be seeing a tab with your last played games. If the TW game for which you want to download mods is not in that list then please click on the search bar to the right of the list and search for the game. Once you see the name of your game click on it. You are now in the community tab of the game. Now click on the "WORKSHOP" header in that Tab. Here´s a picture where I highlighted the different steps in case you didn´t understand what I was talking about: [[File:Downloading Mods|thumb]]
Now you search for the mods you want to use. Once you have found them you click on the subscribe button and Steam should start the download automatically.
=== Using KMM ===
Here´s a picture so you can understand my description better:
[[File:Using KMM|thumb]]
== NR1: Options ==
* "Use last profile" and "Highlight recent mods" are pretty self-explanatory and should in my opinion both be ticked.
* "Backup Mods" and "Choose Backup Location" are still self-explanatory. Click on "Choose Backup Location" to choose where your backup should be saved and check "Backup Mods" to actually enable the Backup function.
* "Choose PFM location" and "Choose RPFM location" is used to set the path to the respective manager. (Pls don´t use PFM thought instead use RPFM)
* "Detect Game Installations" is used to retrigger the game detection if you have a new TW game you want to use mods for.
* "Bypass CA launcher" does what it says when ticked and should always be ticked in my opinion.
* "Bypass Conflict Detection" should be ticked unless you have a real need for it. But mostly you won´t.
== NR2 and 2*: Profiles ==
* You can make a new profile by enabling the mods you want in it and then naming it in the text field (2*) and click save and you have your new profile.
* You can export your currently open profile via the "Profile" header (2). It will be saved as a txt file in the location you choose.
* You can import a profile if you have the txt file for it. You do this via the "Profile" header (2). It will automatically only enable the mods you are subbed to and are in that profile and disable all others.
== NR3: Game ==
* You can see all games supported by KMM (grey names) and the ones which are supported and KMM detected (black names) when you click on the "Game" header.
== NR4: Tips ==
* Here you see some good tips and info for using KMM
== NR5: Version ==
* You can see the version you use in the top row and the latest version available under the headers. Make sure to always use the newest version.
== NR6: Number of Mods ==
* You can see how many mods you have enabled in the top, left of the tips and info section.
* You can see the number of movie mods you have over the start button. Movie mods are always active regardless of if you activate them or not. So be aware of that. You can see which mods are movie mods by sorting via the "type column".
* You enable mods by checking the small box left of their name.
== NR7: Launching and Refreshing ==
* The refresh button over the launch button is used to refresh KMM if you downloaded any mods while KMM was open so KMM becomes aware of the new mods.
* You launch the game by clicking on the launch button.
=== Enabling mods (CA/Vanilla Launcher) ===
So you have succesfully downloaded a mod. Congratz! But you have decided against using KMM. Well it´s not my part to judge...
You enable mods by starting your game like you normally do but before you click on the play button inside of the TW launcher you click on the "Mod Manager" header on the left right next to the "Game" and "Shop" header.
Then you should be in the CA mod manager. There you search through the list of mods and click on the grey bar on their left to enable them. They should then turn green. Once you have enabled all the mods you want to use you click on the big play button in the upper right. You now get a popup that lists all enabled mods. Look through them if you forgot to enable some and then accept the popup. Here´s another picture to simplify:
[[File:Enabling Mods|thumb]] Congrats! You now succesfully activated a mod!
=== Good Practices ===
* Don´t change Loadorder! Only do this if you are aware of what you are doing there and even then only do this if you have a good reason!
* If you have issues with mods try to fix them yourself first (I recommend Cataph´s excellent guide: [[Troubleshooting|Troubleshooting Guide]] ) and only if you have confirmed it is a problem with that particular mod contact the author. Most of us prefer Discord but Steam works as well.
* Don´t be obnoxious. Almost all of us are doing Modding as a hobby and not as a job. So don´t spam "UPDATE PLS" for example. There might be a very good reason why we didn´t update our mod yet or we just didn´t have time yet.
=== Differences if you are using Epic Games instead of Steam ===
I have no idea as I don´t own a TW Game on Epic. But if you do and know what´s different for epic games then please fill in this section.

I’ll add more information later if people have questions or I forgot anything.

File:Using KMM.PNG

2021-03-29T10:31:26Z

Fenriswolf: File uploaded with MsUpload

File uploaded with MsUpload

File:Enabling Mods.PNG

2021-03-28T22:59:13Z

Fenriswolf: File uploaded with MsUpload

File uploaded with MsUpload

File:Downloading Mods.PNG

2021-03-28T22:23:17Z

Fenriswolf: File uploaded with MsUpload

File uploaded with MsUpload

Modding

2021-03-24T20:25:42Z

Fenriswolf:

Modding, or creating [[mods]], is the act of modifying the game files in order to cause changes or create new behavior within the game. There's a lot that can be done with modding - this page seeks to be a clear outline of what modding is, what you can and cannot mod, and other important high-level concepts.

If you're looking for [[installing mods]], check that page.

And you can check the [[Tutorial:Main Page|modding tutorials]] page for a portal about various available, specific tutorials.

== What's a Mod ==
A mod - short for "Modification" - can be anything user-created that edits the game in a meaningful way.

In the Total War series, mods are composed of a single file - a .pack file - which contain all of the changes within that mod. Packs act like a .zip or .rar file, a compressed folder in a single file. Much of the vanilla game is composed of various CA-made pack files.

Packs can contain a lot of various pieces, such as:

* '''Data:''' One of the most-used parts of a mod is databasing. Total War uses database files, similar to spreadsheets, which can be used to change behavior and values, or add new objects to the game. This is used for much of the game, from units and their stats to the cost of buildings and much in between.
* '''Text:''' On top of that, text you see in the game - from the name of a lord to the flavour text of a skill - is done within packs, in .loc files. These files attach text to the database, and they can be used for translations as well!
* '''Assets:''' This is a wide topic - but much of the game can be edited through assets. Assets range from .png images scattered throughout the UI, to altered .dds files which are used on the various unit models in the game, to entirely new models or otherwise.
* '''Battle Maps:''' Battle maps are created through the Terry tool, from within the [[Assembly Kit]].
* '''Scripts:''' There's a layer of the game that can be interacted with through scripts (.lua files). Scripts power things such as characters getting experience, legendary lord defeat traits, and the Chaos Invasion - and much in between!

There's natural limitations to modding the game, since the game is written in a way that cannot be decompiled easily - meaning much of the game code and engine is unreadable and untouchable. That said, Creative Assembly does a comparatively excellent job at making sure much of the game is exposed to being modified!

== Getting Started ==
You've decided on a general mod idea you want to do, and you're ready to set aside some time to try, fail, try, fail, try and then inexplicably succeed the third time. This is the spot for you!

First thing's first, before you go on, you need to grab the [https://github.com/Frodo45127/rpfm/releases/latest Rusted Pack File Manager], by Frodo. It's the primary tool available to create a .pack file, edit it, and manipulate it in whatever way, and comes with a lot of excellent functionality.

Right after installing RPFM, you should decide on a folder on your computer that you'll store your mods. This'll be your primary directory for modding. For instance, I have S:/modding/ determined as my main spot on disk. Name it whatever you want, put it wherever you want.

Then, within RPFM, open the Preferences menu (through Ctrl+P, or PackFile -> Preferences), and begin to set up the necessary preferences within. Target all of the folders for all installed Total War games, targeting the folder where the .exe of the game is. Underneath, in "MyMod's Folder", fill in your new folder.
[[File:Screenshot 2021-01-31 205343.png|left|thumb|710x710px|Fill in your MyMod folder here!]]

Fill out whatever other preferences you may like, but most of this stuff you'll see through time. Keep "Allow Editing of CA PackFiles" to false, I prefer to have all of the checks valid on start, and of course the Use Dark Theme setting is an absolute must.

With RPFM, we can do an absolute load of modding. I recommend [[Setting up GitHub|using GitHub]] for version and source control - it's saved me several dozen times when I almost certainly would've lost an entire mod, or gotten two versions (ie. an update version and the retail version) mixed up.

You may also want to download the [[Assembly Kit]] for the game you're modding, as well as [https://www.microsoft.com/en-us/microsoft-365/excel Excel] or another spreadsheet program - it can come in hand a billion times over.

With all of our tools set up, we can get [[First Mod|started on our first mod]]!

== Guidelines ==
This is a list of hopefully helpful tips for modders - new or old.

* '''Start small, build up.''' One of the oldest tricks in the book is having a tremendously bloated idea, trying to make it all at once, getting overwhelmed, and then quitting. We've literally all done it. Instead of trying to build a pyramid from the bottom up, try to build a glacier from the top down, starting with a simpler idea and continuing it naturally.
* '''Ask for help.''' The Total War modding community, especially that around the Modding Den Discord, is a big help - you're not in this alone.

Modding

2021-03-24T20:08:35Z

Fenriswolf:

Modding, or creating [[mods]], is the act of modifying the game files in order to cause changes or create new behavior within the game. There's a lot that can be done with modding - this page seeks to be a clear outline of what modding is, what you can and cannot mod, and other important high-level concepts.

If you're looking for [[installing mods]], check that page.

And you can check the[[Tutorial:Main Page|modding tutorials]] page for a portal about various available, specific tutorials.

== What's a Mod ==
A mod - short for "Modification" - can be anything user-created that edits the game in a meaningful way.

In the Total War series, mods are composed of a single file - a .pack file - which contain all of the changes within that mod. Packs act like a .zip or .rar file, a compressed folder in a single file. Much of the vanilla game is composed of various CA-made pack files.

Packs can contain a lot of various pieces, such as:

* '''Data:''' One of the most-used parts of a mod is databasing. Total War uses database files, similar to spreadsheets, which can be used to change behavior and values, or add new objects to the game. This is used for much of the game, from units and their stats to the cost of buildings and much in between.
* '''Text:''' On top of that, text you see in the game - from the name of a lord to the flavour text of a skill - is done within packs, in .loc files. These files attach text to the database, and they can be used for translations as well!
* '''Assets:''' This is a wide topic - but much of the game can be edited through assets. Assets range from .png images scattered throughout the UI, to altered .dds files which are used on the various unit models in the game, to entirely new models or otherwise.
* '''Battle Maps:''' Battle maps are created through the Terry tool, from within the [[Assembly Kit]].
* '''Scripts:''' There's a layer of the game that can be interacted with through scripts (.lua files). Scripts power things such as characters getting experience, legendary lord defeat traits, and the Chaos Invasion - and much in between!

There's natural limitations to modding the game, since the game is written in a way that cannot be decompiled easily - meaning much of the game code and engine is unreadable and untouchable. That said, Creative Assembly does a comparatively excellent job at making sure much of the game is exposed to being modified!

== Getting Started ==
You've decided on a general mod idea you want to do, and you're ready to set aside some time to try, fail, try, fail, try and then inexplicably succeed the third time. This is the spot for you!

First thing's first, before you go on, you need to grab the [https://github.com/Frodo45127/rpfm/releases/latest Rusted Pack File Manager], by Frodo. It's the primary tool available to create a .pack file, edit it, and manipulate it in whatever way, and comes with a lot of excellent functionality.

Right after installing RPFM, you should decide on a folder on your computer that you'll store your mods. This'll be your primary directory for modding. For instance, I have S:/modding/ determined as my main spot on disk. Name it whatever you want, put it wherever you want.

Then, within RPFM, open the Preferences menu (through Ctrl+P, or PackFile -> Preferences), and begin to set up the necessary preferences within. Target all of the folders for all installed Total War games, targeting the folder where the .exe of the game is. Underneath, in "MyMod's Folder", fill in your new folder.
[[File:Screenshot 2021-01-31 205343.png|left|thumb|710x710px|Fill in your MyMod folder here!]]

Fill out whatever other preferences you may like, but most of this stuff you'll see through time. Keep "Allow Editing of CA PackFiles" to false, I prefer to have all of the checks valid on start, and of course the Use Dark Theme setting is an absolute must.

With RPFM, we can do an absolute load of modding. I recommend [[Setting up GitHub|using GitHub]] for version and source control - it's saved me several dozen times when I almost certainly would've lost an entire mod, or gotten two versions (ie. an update version and the retail version) mixed up.

You may also want to download the [[Assembly Kit]] for the game you're modding, as well as [https://www.microsoft.com/en-us/microsoft-365/excel Excel] or another spreadsheet program - it can come in hand a billion times over.

With all of our tools set up, we can get [[First Mod|started on our first mod]]!

== Guidelines ==
This is a list of hopefully helpful tips for modders - new or old.

* '''Start small, build up.''' One of the oldest tricks in the book is having a tremendously bloated idea, trying to make it all at once, getting overwhelmed, and then quitting. We've literally all done it. Instead of trying to build a pyramid from the bottom up, try to build a glacier from the top down, starting with a simpler idea and continuing it naturally.
* '''Ask for help.''' The Total War modding community, especially that around the Modding Den Discord, is a big help - you're not in this alone.