HowTo: Set up MTW2 for modding

[alpaca]

You can quote or link to this tutorial at wish, but please don't mirror it. This is required to keep discussion about it all in one place.

Setting up MTW2 for modding

In this tutorial I want to walk you through the necessary or at least very useful steps to set up a working modding environment.

This can be done using one (or both) of two different ways:
- Creating mod folders
- Making the game recognize files you put in the data directory (using the io.file_first switch)

Both ways have their own advantages and disadvantages, but overall I feel that mod folders should be the first choice, unless you want to do something they don't support (more on that later), but I will nonetheless describe both methods.



1. Getting the files

Well, the first step of setting up your game will always be unpacking the data files, no matter if you want to use mod folders or io.file_first.
To do this, you have to have patch 1.1 installed. If you do, you should be able to find a directory called "tools" inside your MTW2 directory, and inside that, you will find a folder named "unpacker".
To unpack all the game's data files, simply run unpack_all.bat - this will take a while, so be warned. After the program's finished, open your data directory (inside your MTW2 directory) and delete or rename descr_geography_new.db and descr_geography_new.txt (this is important - if you don't do it, your game won't run)

Information for advanced users:

Spoiler Alert, click show to read: 

I recommend editing unpack_all.bat to not unpack into your vanilla data directory, but into a subfolder. This way, you can always keep a clean copy of the files.
To do this, open up the batch file and edit it like this:

unpacker.exe --source=..\..\packs\*.pack --destination=..\..\backup --verbosity=1

That will unpack the files into a directory called backup inside your MTW2 folder.

You should also copy the data/world/maps/base and data/world/maps/campaign/imperial_campaign folders to this directory

1.1 Converting the text files

The next step after unpacking is due to the fact that the game stores the localised text in files with the extension .strings.bin - however in order to edit them, you want to have them in .txt format (UTF-16 if you know what that is). The game will then automatically generate the .strings.bin files from these txt files.
I wrote a useful python script that allows batch conversion of these files. You can find it here
Usage instructions can be found in the read-me file for the tool.

1.2 Alternative: Directly editing the .strings.bins

pmcorp wrote a nice tool that allows you to edit the .strings.bin files directly. I prefer converting them and editing them in my favourite text editor, but I guess some people prefer to directly edit the bin files.
Further, this tool allows you to edit the files my converter can't convert, so you should definitely get it at least for that end (click here).
Be aware that you will have to install the .net frameset before being able to use this (get it here or the 64-bit version here)



2. Mod folder vs. io.file_first

In the next step, you will have to decide whether you want to use a mod folder, or the io.file_first switch for your working environment. To easy your decision, I will state some of the advantages/disadvantages for both methods:

Mod folders:
pro:
- You can have multiple mods at once without them interfering with each other
- When changing mods you don't have to switch out any files
- Savegames, preferences, etc. can be kept separately for each mod

contra:
- Not all files are supported, this includes textures. For more information, visit this link
- Slightly harder to set up

io.file_first:
pro:
- Supports all editable files
- Slightly easier to set up

contra:
- When changing mods you have to switch out all modified files
- Savegames, preferences, etc. have to be switched out, too
- You will always overwrite your unpacked files


3. Setting up a mod folder

The easiest way to set up a new mod folder is probably using my mod folder installer
It will allow you to easily set up a mod folder with all the necessary files.
For manual instructions, click on show:

Spoiler Alert, click show to read: 

First of all, create a new folder inside your MTW2 directory called "mymod" (you can replace mymod with anything you like, as long as you keep replacing it throughout the rest of this section).


3.1 Creating a new config

To do this, copy your medieval2.preference.cfg file and name the copy "mymod.cfg"
Then open "mymod.cfg" with a text editor and add the following to the top:

[features]
mod = mymod

[log]
to = logs/system.log.txt
level = * error

The first setting tells the game the mod folder in which it should look for files, the second enables error logging to a custom error log file which is highly recommended, but not exactly required.


3.2 Necessary files

Before proceeding, please create a data folder inside your "mymod" folder.
In order for your mod folder setup to work, you will have to copy data/world/maps/base and data/world/maps/campaign/imperial_campaign, as well as text/imperial_campaign_regions_and_settlement_names.txt to your "mymod" directory, leaving the directory structure intact (i.e. data/world/maps/base should go to mymod/data/world/maps/base, etc.)


3.3 Optional files

On top of this, you may want to copy the following:
- To enable sounds, data/sounds/events.dat and data/sounds/events.idx
- To enable loading screens, data/loading_screen
- To enable event videos, data/fmv

Of course, you should also copy any files you want to edit into the data directory of your mod folder.


3.4 Batch file creation

In order to be able to start your game using your mod folder, create a new text file inside your MTW2 directory called mymod.bat
Open it (right-click, edit) and write this into it:

medieval2.exe @mymod.cfg

Congratulations. If everything worked, you should now be able to run the game with your mod directory by starting mymod.bat



4. Setting up io.file_first

4.1 Creating a new config

To do this, copy your medieval2.preference.cfg file and name the copy "mymod.cfg"
Then open "mymod.cfg" with a text editor and add the following to the top:

[io]
file_first = 1

[log]
to = logs/system.log.txt
level = * error

This will tell the game to use the files it finds in the data directory instead of those in the packs.
It will also enable error logging to a custom error log, which is highly recommended, but not strictly necessary.

In order to be able to start your game using this config, create a new text file inside your MTW2 directory called mymod.bat
Open it (right-click, edit) and write this into it:

medieval2.exe @mymod.cfg

Congratulations. If everything worked, you should now be able to run the game with your unpacked files by starting mymod.bat



5. Testing

An easy test is editing a screen text file (for example text/imperial_campaign_regions_and_settlement_names.txt) and replacing one entry with something different. If your change shows up in the game, you're set up fine. I usually do something like changing

{London}	London

to

{London}	The Moloch

If you then start the game as the English, London should (more or less) rightfully be called "The Moloch" - if it isn't, your modding environment is not set-up correctly.



6. The error log

This doesn't really fit here, but as it is probably somewhat of a beginner tutorial, I want to make sure you understand how important the error log is.
Remember what you added into your config file:

[log]
to = logs/system.log.txt
level = * error

This tells the game to create an error log in the MTW2/logs folder called system.log.txt

A lot of common errors will be shown in this log, so if something doesn't work, or the game crashed, it's a good idea to check this log file before doing anything else.
As you are a beginner, it will probably tell you what's wrong in at least 50% of the cases, and although its usefulness will decrease slightly once you're getting more experienced, it will still be a routine action to check this file every time you quit the game.

The progression for log levels is trace<info<warn<debug<err<fatal<always
Usually, the most useful one is level = * err or level = * error because it will show you the errors you make (like spelling mistakes and so on) without giving a lot of unnecessary info. However, if you're creating triggers or scripts and want to test them you should use level = game.script.* trace as it will yield all the info about the scripting side of the game, including triggers.
I don't think there are any debug messages in the retail exe so debug is the same level as err
The warn level can be useful sometimes if you want info about missing files and so on but you'll have to dig through a lot of stuff to find it.

There's a few issues with this file, for example you can't guarantee when it writes the log unless you close the game. So it may be a good idea to only test one thing at a time and then close the game again in order to be able to catch as many problems as possible.