Modding Guide

A guide to modding the game. You can change a number of graphical elements, add new character portraits, modify a selection of numerical values used by game mechanics and modify unit stats.

I will expand this guide as new ways to mod the game are added.

Introduction

Modding support is continually being expanded, with patches and updates adding new ways to mod the game.

Mods are created by placing a folder each under "/Mods/" in the user-specific data folder (also used for save games and settings).

When you download a mod from the Steam Workshop it does not reside in the regular Mods folder, but is placed in a folder created by the Steam client. The game will automatically detect any subscribed and downloaded mods.

If you wish to modify a mod downloaded from the Workshop you need to place a copy of the mod in the "/Mods/" folder and modify that version. The Mods window in the game has a link to the file system path of the Workshop mod.

Mod Management

Place a subfolder below /Mods/ in the user data folder (this can also be done via the Mods Window).

An example of where this could be found:
C:\Users\<myusername>\AppData\LocalLow\Valravn Games\Wizards and Warlords\Mods\

The Mods dialog in the game menu should indicate this location to you.

Creating a Mod could thus result in a folder like this:

C:\Users\<myusername>\AppData\LocalLow\Valravn Games\Wizards and Warlords\Mods\MyMod\

Placing various files and folders inside this folder will determine the behavior of the mod.

You should always place a toc.txt file in a mod folder. The in-game Mod Management has a button to help you create a default toc.txt as part of creating mod.

The first line in this file will be read as the name of the mod. Otherwise the folder name will be used.

The second line is the unique ID of the mod. It should be a valid Guid. If you don't use the in-game mod management, I recommend using an online Guid generator. This is used to uniquely identify Mods, so if you copy an existing mod for modification, remember to change the Guid in the new mod.

An example of a toc.txt file:

My Awesome Mod
b7b9b747-2bae-441c-a872-bf219e770901

Mechanics and Rules: Constants

Various numerical values used by the game can be changed by adding a mechanics.txt file to the mod folder.

To change a value you need to add a line for each of them to file using the following format

key:value

For example:

ManaNodeBindCostLarge:500
ManaNodeBindCostMassive:600
ManaNodeOutputLarge:8
ManaNodeOutputMassive:12
MasteryProgressUnitWeight:0.2
MasteryProgressSpellWeight:0.1
MasteryProgressManaNodeWeight:10.0

Integer keys

Key	Description
WizardCustomizationPoints	Number of point used to create Custom Wizard. Default is 8.
ManaNodeBindCostMinor	Mana Cost to Bind a Minor Node. Default is 100.
ManaNodeBindCostSmall	Mana Cost to Bind a Small Node. Default is 250.
ManaNodeBindCostMedium	Mana Cost to Bind a Medium Node. Default is 450.
ManaNodeBindCostLarge	Mana Cost to Bind a Large Node. Default is 750.
ManaNodeBindCostMassive	Mana Cost to Bind a Massive Node. Default is 950.
ManaNodeOutputMinor	Mana produced per turn by a Minor Node. Default is 1.
ManaNodeOutputSmall	Mana produced per turn by a Small Node. Default is 3.
ManaNodeOutputMedium	Mana produced per turn by a Medium Node. Default is 6.
ManaNodeOutputLarge	Mana produced per turn by a Large Node. Default is 12.
ManaNodeOutputMassive	Mana produced per turn by a Massive Node. Default is 18.
BaseManaCap	Base resource cap for Mana (maximum amount stored). Default is 800.
ChannelingManaCapBonus	The bonus to Mana resource cap from the Channeling Wizard Trait. Default is 250.

Floating-point keys

Key	Default Value	Description
MasteryProgressSpellWeight	1.0	Weight applied to the mastery progress contributed by casting spell.
MasteryProgressUnitWeight	1.0	Weight applied to the mastery progress contributed by units.
MasteryProgressManaNodeWeight	1.0	Weight applied to the mastery progress contributed by Mana Nodes.
MasteryProgressSpellManaWeight	0.5	Weight given to Mana Cost when calculating the mastery progress contributed by casting spells.
MasteryProgressSpellLevelWeight	0.5	Weight given to Spell Level when calculating the mastery progress contributed by casting spells.

Adding/Changing Character Portraits

Adding a Portrait folder below a Mod can be used to extend the number of available portraits used by the game when assigning these to characters.

Custom portraits need to be given an id from 1000 and up. For each portrait place the corresponding image file in the folder and prefix por to the id as the filename. For example, one might create 3 new portraits and add them as files

por1000.png
por1001.png
por1002.png

If this was for a hypothetical mod using the sub-.folder HappyFaces, all these would be put in the folder:

/Mods/HappyFaces/Portraits/

Note that the in-game Mods window will create Mods without a Portraits folder, so this has to be added manually.

To control how custom portraits are used add a text file named info.txt to the same folder as the images. (Just one, not one for each portrait).

You can add a line for each portrait (but you don't have to) with following format:

id;keyword1;keyword2;keyword3

You can have any number of keywords. For example this could look like this:

1000;male;dwarf
1001;female;dwarf;*rogue
1002;bothgenders;demon;priest

The game uses this information when assigning the portraits. Prefixing with an asterisk denotes the keyword as optional. Prefixing with an exclamation mark denotes the keyword as invalid (use for alignments for now - untested with everything else). Keywords include:

Use up to one of these:
male
female
bothgender

Race-based keywords:
dwarf
elf
demon
orc
bugbear
dragon
goblin
vampire
stonemen
ape
ogre
halfling
gnome
ratman
troll
lizard
hobgoblin
gnoll

Alignment-based keywords:
good
neutral
evil

Class-based keywords:
martial
scholar
arcane
rogue
mercantile
artisan
religious
(and any class names as seen in-game - more info later)

Hint-only keywords:
beard
armor

Hint-only keywords:
savage
primitive
barbarian
cultured
semicultured
highlycultured

Culture traits can also be used as hint keywords (see encyclopedia - exhaustive list coming to guide later)

Adding Sigils

You can add new faction sigils. This refers to the image used by a faction as part of the faction banner/emblem, and chosen by the player during game setup. Modded sigils currently cannot be used by AI factions.

To add sigils to a mod create a folder named "/Sigils/" inside the mod folder. For example a hypothetical GrimEtchings mod would have a folder like this:

/Mods/GrimEtchings/Sigils/

You can then place any number of image files in the folder, and they will be loaded as part of the mod and added to the selction of mods.

Changing Map Graphics

Map graphics can be modded - providing a custom texture for one or more hex terrain types. This can be added to any mod by placing a MapGfx folder inside the mod folder (similar to the Portraits folder used for adding/changing character portraits).

For example a hypothetical mod named NeonInvasion could have a folder like this

/Mods/NeonInvasion/MapGfx/

Terrain Types

Inside this folder you will then need to an info.txt file which links custom images to terrain types, and the custom images themselves.

The custom images must be 1024x1024. The following image shows what part of the image should be used for the hex texture (pink) and what should be transparent background.



For each in-game terrain type that you want to provide a custom image for, you must add a line to the info.txt file with following format:

imagename;terraintype

The imagename can be with or without extension. The terrain type must be from the list at the end of this section. Here is an example overriding three terrain types.

pink.png;forest
yellow.png;desert
cyan.png;ocean

Terrain Type Identifiers

Terrain Type	Valid Identifiers
Plains	0 plains
Grassland	1 grassland grasslands
Swamp	2 swamp
Forest	3 forest
Shrublands	4 shrublands shrubland
Marsh	5 marsh
Hills	6 hills
Forested Hills	7 forestedhills forested_hills forested hills
Mountains	8 mountains
Forested Mountains	9 forestedmountains forested_mountains forested mountains
Arid Plains	10 aridplains arid_plains arid plains
Rocky Badlands	11 rockybadlands rocky_badlands rocky badlands
Arid Hills	12 aridhills arid_hills arid hills
Arid Mountains	13 aridmountains arid_mountains arid mountains
Desert	14 desert sandydesert
Desert Hills	15 sandyhills deserthills desert_hills desert hills
Desert Mountains	16 sandymountains desertmountains desert_mountains desert mountains
Frozen Plains	17 arctic plains frozenplains frozen_plains frozen plains
Tundra	18 tundra
Taiga	19 arcticforest taiga
Frozen Hills	20 arctichills frozenhills frozen hills frozen_hills
Frozen Mountains	21 arcticmountains frozenmountains frozen_mountains frozen mountains
Jungle	22 jungle
Magma Plains	23 magmaplains magma_plains magma plains
Ocean	24 ocean

Changing Unit Type Stats

To change the stats of one or more Unit Types, you can export a unitTypes.xml via the Mods Window in the game. This file can then be placed into a Mod folder and edited - and the stats will changed when using the Mod in a game.

It is highly recommended to only include any changed Unit Types in this xml file. In other words, remove all unmodified Unit Types.

his way any changes to unit stats (in patches/game updates) will be used and not overriden by the 'old' defaults in the file.

I haven't had time to document the file format used so far, but if you are familiar with xml it should be relatively easy to navigate the file format. Otherwise I recommend looking up some basic guides on xml and/or using an xml editor utility. The format used is very basic and does not require a deep understanding of xml.

Changing Unit Icons

If you create a UnitGfx folder inside your Mod folder, you can replace default unit icons with custom ones.

/Mods/MyMod/UnitGfx/

Create an info.txt fil within this folder to map the image to unit types. Each line maps one such pair. Example:

GiantWolves;wolfie
DireWolves;wolfie
AngelsOfHope;angel

Will map wolfie.png to the two wolf types mentioned and angel.png to the angels of hope.

Images should be rectangular and ideally power of 2 in size (32, 64, 128, etc.). They will be scaled to the relevant size by the game, but be aware that using extremely large textures may cause memory issues.

To see the full list of unit identifiers, you can export a unitTypes.xml file.

Unit Icon (override built-in)
Another way to modify Unit Icons is to override the built-in icons, but without changing the mapping as in the previously described method. To do this create a UnitIcon folder

/Mods/MyMod/UnitIcon/

Any images placed in this folder will be used to override the built-in unit icons and used wherever that icon would be used.

These are the currently valid icons you can override:

sword, archer, light_cavalry, heavy_cavalry, heavy_infantry, pikeman, shield_infantry, irregular, bear_paw, wolf_paw, monster_claw, air, fire, water, earth, runestone, savage_tusk, headstone, cogs, monster_wing, questionmark, wisp, dragon, red_maw, moon_demon, snake, spider, bloody_axe, hoof, green_lurker, eshim, giant, dryad, celestial, lesser_fae, demon_light_infantry, treant, frost, greater_fae, imp, zombie, griffon, worm, scorpion, bat, boar, eagle, lizard, crocodile, crab, frog, chaos_humanoid, pirate, metal_humanoid, death_valkyrie, voidling, death_shade, barbed_horror, tormented, demon_siege_beast, hellhound, demon_vulture, demon_mercenary, demon_brute, plague_demon, succubus, incubus, reality_thief, lesser_elder_spawn, elder_spawn, fleshflect, psychopolyps, deep_fish, light_elemental, void_elemental, frost_elemental, acid_elemental, lightning_elemental, phoenix, mercury_elemental, redcap, satyr, faun, nymph, radiant_soldier, treant_sapling, dragon_knight, shadow_knight, chaos_knight, talon, grey_ooze, vile_slime, skeleton_mage, undead_beast, ghost, spirit_hound, vampire, lich, death_knight, draugar, banshee, risen_champion, archon, centhorian, medusa, yeti, mudman, feral_troll, feral_ogre, rime_troll, stoneperson, crystal_humanoid, fomorian_noble, fomorian_elder, monster, gargoyle, horse, mummy, scarecrow, rabbit, stormling, lesser_angel, valkyrie, lesser_shade, shade, greater_shade, light_wolf, dark_wolf, fire_lizard, ghoul, skeleton_generic, skeleton_monstrosity, ancient_spirit, blood_beast, raven, great_caw_paw, dinosaur_1, dwarf_very_light, dwarf_light, dwarf_medium, dwarf_heavy, dwarf_super_heavy, dwarf_irregular

Dynamic/Culture Unit Types:

In order to override icons for the unit types generated as part of each game world, you must create a "cultureunits.txt" file and place it in the UnitIcon folder.

Each line in this file will override the graphics for a specific unit type template for a specific race.

Orc;IrregularInfantry;light_orc_infantry;100
Orc;LightInfantry;light_orc_infantry;100
Orc;EliteInfantry;elite_orc_infantry;100
Orc;LightCavalry;light_orc_cavalry;200
Orc;Cavalry;orc_cavalry;100
Hobgoblin;Infantry;hobgoblin_infantry;100
*;Infantry;generic_infantry
*;HeavyBrigandInfantry;angry_bandits;500

The valid values for the first item (race):

*, Human, Ape, Monkey, Gorilla, Beastman, Bugbear, Centaur, Dragonman, Dwarf, Elf, Gnoll, Flind, Gnome, Goblin, Halfling, Harpy, Hobgoblin, Insectoid, Leonid, Lizardman, Minotaur, Ogre, Orc, Stoneman, Troll, VampireTroll, Ettin, Cyclops, Gorgosi, Deuadai, Fungoid, Crystalline, Draconic, Serpentoid, Arachnoid

If a * is supplied, the line will apply to all races.

The valid values for the second item (unit template type):

IrregularInfantry, LightInfantry, MediumInfantry, HeavyInfantry, LightMissileInfantry, MediumMissileInfantry, HeavyMissileInfantry, LightMissileCavalry, MediumMissileCavalry, LightCavalry, MediumCavalry, HeavyCavalry, Pitfighters, EliteInfantry, EliteHeavyInfantry, EliteScoutInfantry, EliteCavalry, EliteMissileInfantry, EliteHeavyCavalry, SlaveInfantry, Pirates, ScoutInfantry, LightWarmachine, MediumWarmachine, HeavyWarmachine, LightBrigandInfantry, HeavyBrigandInfantry, BrigandMissileInfantry, LightBrigandCavalry, MediumBrigandCavalry, LightChariots, MediumChariots, HeavyChariots

Other valid values for the second item (unit template type traits):

VeryLight, Light, Medium, Heavy, SuperHeavy, Infantry, Cavalry, Charioteers, Warmachine,        Irregulars, Militia, Professional, Elite, LongRangeMissile,  ShortRangeMissile, Scouts, Sappers. Spellcasters, Amphibious, Berserkers, HolyWarriors, Chivalric, Pirates, CityGuards, BorderTroops, PersonalGuards, Nobles, GunpowderMissile

The third item is the filename (without extension) of a unit icon in the mod folder

The (optional) fourth item is the numerical priority to use if multiple lines apply to a unit type. The highest priority will apply. The default value (if not supplied) is 0.

Changing Unit Experience Graphics

(1.0.2.66+)

In order to modify the Unit Experience Graphics you must create a UnitLevelGfx folder inside your mod folder.

In this folder you can place the image files to be used as override for the mod.

By using a text file named info.txt within the UnitLevelGfx you can control how to override the default graphics.

You can use any of the following in this file (one per line):

leveltext;(false/true/true_if_no_main)
mainsprite;(lvl);(image)
framesprite;(lvl);(image)

leveltext is used to control whether a text representation of the unit experience level should be shown (the default is true). true_if_no_main will show text if no mainsprite override exists for the level. Text is never shown for level 0.

mainsprite is used to show an image within the frame of the level display. This could be star(s), chevron(s) or something similar. You can indicate one level or a range. By default no such image is shown. For example:

mainsprite;2-5;copper
mainsprite;6-9;silver
mainsprite;10;gold
leveltext;true_if_no_main

This will show the copper image file (file extension should not be included) for level 2-5, silver for 6-9 and gold for 10. No images are shown for 0 and 1. Due to the leveltext line, text will be shown for 1.

framesprite is similar to mainsprite but affects the frame of the level display. By default a copper frame is shown for 0 to 3, silver for 4 to 7 and gold for 8+. If a level is not overriden the default graphics are used. For example:

framesprite;9;platinum
framesprite;10;legendary

This will override level 9 and 10 with custom frames. The default frames are used for other levels.

Road Map: Additional Options

A road map of further Modding support. Subject to change.

Constants
Adding new constants to those already exposed.

Spell Creation:
Adding new spells, based on effect templates and very simple logic-based scripting, specifying whether they are Mastery Unlocks or Research Projects.

New Unit Creation:
Add new unit types, specifying whether they are Mastery Unlocks or Research Projects.

City Buildings
Change city buildings stats. Add new building types.

Known Issues

[sir Evans]

Let me ask this:
"To see the full list of unit identifiers, you can export a unitTypes.xml file."

How can we do exporting? Ingame somewhere, etc?

[Elindos Phar & Family]

So where are we now regarding roadmap and released mod features?
anything to update on this excellent thread?

(thanks again for this great service, by the way!)

[sir Evans]

Ok, that was incorrect guid issue. Interesting.

[sir Evans]

thanks, I'll check it out!

[Valravn Games]

@sir Evans
(addendum to previous reply) I'll see if I can improve mod logging as well to catch more potential problems with the mechanics file.

[Valravn Games]

@sir Evans
There is a mod in the workshop which modifies customization points and nothing else. You could try compare your mod with that one. I will test if something is broken as well.

[sir Evans]

not sure if mechanics.txt works as intended.
I have created this file in root mod folder with a single entry
WizardCustomizationPoints:12

and nothing happened :)
No info in the log. Could this be to invalid guid? I don't think so, but.

[Valravn Games]

@Gumdrop Thief

Power of two. They will be automatically scaled to where they are used in the UI. It will affect memory usage if they are large, but it can provide some additional quality on high-resolution displays. I would suggest 256x256 or 512x512 as a general rule of thumb.

[Gumdrop Thief]

Ideally what size should the images be in width and length for custom follower portraits?

[Valravn Games]

@Elmor

Not yet, I am afraid. I have in-progress translation support, but as I'm always struggling for development bandwidth (ie time), there is still a fair bit of work left on it. It is probably possible to use some of the code-injection Unity modding libraries to create a translation, but maintaining that would be a massive pain, so I won't recommend that. Hopefully I'll find a way to get the game-support translation support to a level where it can be enabled even though not all text pieces are exposed to it yet. But when I'll be able to spend time on it again, I'm not quite sure.