HOI4 Modding : The First Steps

Starting to mod in HOI4 is a long journey. HOI4 and in fact most Paradox games are very easy to mod, and spending a small amount of time to learn the code is enough to start modding; however this isn't the case for adding new graphics, provinces or juggling with interface files, which has no documentation at all. It can also be frustrating to learn coding in the first place. If you're clueless on how to start up, stuck or just want some shortcuts, you've come to the right place.

This guide will focus on giving the player a basic grasp on editing localisation files, changing flags and leader portraits. Note that this guide makes the assumption that the reader never has done anything to do with modding, creating content based on coding or anything of that sort. It's focused towards people who've spent their lives reading history books and staring at maps, so discretion is advised to people who are familiar with using coding.

## Good places to start off

The first few steps are a popular topic and various tutorial videos have been made on it. If you don't feel like learning modding from text, you can always receive visual guidance. These are some of the videos powerblo thinks are the most useful for starting off.

https://www.youtube.com/watch?v=wASw6hOJwGM&list=PLBGZyYzya9TUnpm8XTmbIbSabungljqzk&index=2

The playlist by MrKmproductions is by far the most informative and helpful series on Youtube, and help you get quite a far way.

https://www.youtube.com/watch?v=eLAzR3lkpLA&list=PLqRhPbyFDQWjzsuv5IgFYp3OuIF1FCIGF

The playlist made by Paradox themselves are the canon resource, and while they cover several complicated schemes(new resources, province editing etc.) it's not organised or user friendly and I wouldn't recommend it for the fresh green modder.

https://www.youtube.com/watch?v=GajAmhNlU\_4&list=PLt\_7vUaEvaGTL9LHXShuDwAES9ryBFf\_o

These series by The Iron Workshop give several tips on how to make several useful changes, and include a nice introduction on making new provinces.

Along with these videos, the wiki page below shows a good list of sites you can access to learn coding or refer to resources.

## Making your First Mod

While unfortunately Paradox hasn't given a lot of documentation about modding, they've given a lot of useful tools to help the modder get going. One of these is the ability to create an empty mod in mere seconds. When you launch HOI4, you'll notice a "Mod Tools" button in the launcher.
Press it, and go to "Create a Mod". When you get in there, you can tamper with the title of your mod and add new tags. Unless you know what you're doing, it's advised to set your directory the same name as your mod(or an abbreviate of it) without spaces or slashes. The game version should also be set to the latest current version of the game.
Don't worry too much if you feel you've made a mistake; all of these can be edited later. If you've finished with all the new bells and whistles, click create mod and you're ready to go.

### Your New Directory

Mods are located in the folder ~/.local/share/Paradox Interactive/Hearts of Iron IV/mod(Mac and Linux) or C;\Users\<username>\Documents\Paradox Interactive\Hearts of Iron IV\mod (Windows). Inside this folder there should be two nitbits;

* The mod folder, named what you decided your subdirectory was
* The .mod file, containing info on how the game should handle your mod folder

The EonAB .mod file looks like this:

```
name = "End of a New Beginning"

path = "mod/eonab"
tags = {
 "Gameplay"
}
supported_version = "1.4.2"

```

With both of these folders/files, you should be able to select your mod in the game launcher. Right now it shouldn't do anything, but content is something you can stack along with time. But before we get working with brand new content, there's a few precautions and tools you should

now of.

## Guidelines

* Never use Notepad as your default text editor. For simplicity, use Notepad++, for convenient folder management use Sublime Text or Atom. All of them are free; it's recommended to have at least two text editors (powerblo uses Atom to manage his projects and Notepad++ to edit individual files)
* ALWAYS create a workspace folder(where you do the editing) separate from your Paradox Interactive\Hearts of Iron\mod directory. Similarly, never edit vanilla files- those edits are permanent unless you reinstall the game.
* Try not to overwrite vanilla files unless their existence create errors or overwrite your content. It's almost always advised to create separate files for localisation, events, focus trees, etc.
* Use repository managing programs like GitHub to keep track of what you've changed, and to revert any fatal errors you made. Don't forget to upload every minor change to GitHub; if your game has errors it's very easy to go sieve through previous versions if you know what changed through tie.
* Use proper folder merging tools instead of copy-paste like WinMerge.
* Don't forget to use UTF-8 encoding for normal files and UTF-8 BOM files for localisation. Text editors like Atom automatically encode your files into these formats.
* Have a "project" folder that includes all your resources, your workspace, and plans for coordinated modding.
* Always have several backup folders if you don't use GitHub. You won't regret it when your new edits cause CTDs the second you start the game.
* Use AFPs or Graphical Tools to reduce coding time and make coding easier, but always use them with caution. They often have several bugs and might delete everything you've done if you don't backup.
* Proper indentations, comments using # and being smart with paragraphs make reading code much easier for other people. This won't break your game when you don't keep it, but it's much more easier for you as well if you know exactly what's going on with each line of code.
* Consult other modders or other mods to get help with things you can't seem to code - reverse engineering is very useful in both learning and decreasing code time, but never plagiarise other's work.

## Localisation : Adding Loading Tips

Now that we've created the empty template for a mod, it's time to create some dummy content. Localisation files are a good place to start, being easy to edit and create.

Localisation files give names to ingame variables, and add text for descriptions. This is where all the ingame text is rendered from, so editing these files would change the text that appears ingame. **All localisation files are and should be located in <mod>/localisation.** Another important point is that **all localisation files have the .yml extension and are encoded in UFT-8 BOM format.** If you don't know what these are, don't worry; you won't have to worry about these as long as you're smart with how you code.

The most straightforward piece of localisation the player first sees are the loading tips; the lines of famous words written on the bottom of the screen while the game is loading. **The best way to start off with localisation is to copy the file in the vanilla folder and paste it into your mod, so you don't have to go through the encoding.** Create a new folder within your mod called localisation, and copy the loading\_tips\_l\_english.yml file and paste it in there. When you open it, there will be a list of *LOADING\_TIP\_<number>:0 "<loading tip>"* , the code that assigns text to loading tips. **Within a localisation file, the variable name goes behind the :0, and the text goes inside the double quotation marks.** By changing the text inside the double quotes, you can change what the game displays for the loading text. Every single loading tip has an equal chance to appear while loading, so erasing every other one (leaving just one loading tip in) will make only one loading tip appear for the entire loading process.

Using special nitbits of code you can format your loading tips, and in fact any localisation file.

**\n** : The equivalent of typing Enter, adding this annotation jumps the text down one line. Useful for loading tips (you've gotta put the original quoter somewhere) or descriptions when you want them to look tidy. Note that you don't need to put a space after the annotation, like "\nAnd Lewis is to blame."

**\"** : Since the boundaries of the localisation is defined by quotes, to use quotes inside your text wall this annotation is used. This is optional, luckily HOI4 is smart enough to let you use normal quotes. However this is recommended for anyone making large scale projects, or just paranoid about how code looks.

## UTF-8 and the HOI4 language

The traditional Paradox machine, the Clausewitz engine utilises a programming language unique to itself, different from the well known Lua or Java. You don't have to read the stuff below to make portrait or flag mods, but it's recommended to know what you're coding in if you want to be good at it.

* HOI4 has their own 'coding language', making it much easier to code but much less versatile. It's similar to the EU4 or CK2 language, but being a new iteration and a different game there will be several places the code doesn't overlap.
* UTF-8 isn't a language; it's a format where the game can read code from .txt files. Don't go looking for UTF-8 encoders and just see if your text editor can do it.
* Localisations need an extra step named UTF-8 BOM. Not keeping this is a common cause of missing localisation files.
* The HOI language, HOI-ese doesn't utilise ;s or <>s, and links how your code is designed to how it functions. This is why using comments(#) is extremely important so you can keep track and have a clean, bugfree code.
* Indentations(tab and spaces) don't really matter in HOI-ese in function.
* HOI-ese operates using .txt files for most code. .yml files are used in localisation, .gui for interface design and .gfx for designating graphic files.
* HOI-ese is mostly independent from directory for graphic files. This has not been confirmed for coding files, but generally it's important to have thourough knowledge on the HOI4 directories.
* Make sure you don't name any ingame files or variables ￼the same.

We assume that you have basic knowledge of how code works, and have at least common sense on what parentheses or equal signs do. Then now that you've got that through, it's time to start making edits to the actual game.

## Changing Country Leaders

Perhaps the best of modding HOI4 would be adding new leaders to nations. It's one of the more simpler, and straightforward changes to start off with.

Adding new country leaders, or replacing them requires you two edit two things;

* The "history" file of the nation you're adding a leader for
* The portrait for your leader

The history file is the first step of adding a leader, faction, party or researched tech for any nation ingame. They're located in [mod]/history/countries/[TAG].txt. Opening it for the first time is a complicated process; but since we're simply adding new leaders it's simple right now.

Let's take the example of Germany; we're not fond that Hitler is in power and want to place a yodeling person in his place.

In the GER.txt, searching "Hitler" returns this block:

create\_country\_leader = {

name = "Adolf Hitler"

desc = "POLITICS\_ADOLF\_HITLER\_DESC"

portrait = "<directory>"

expire = "<date>"

trait = {

}

1. ↑ Automatic File Processor - A set of .bat files that automate simple actions like creating nation history files or converting flag image files.
2. ↑ They're called loading tips because traditionally (in Paradox games like EU4) they contained tips on how to play the game.
3. ↑ Wherever your HOI4 is installed - the localisations folder