From Hearts of Iron 4 Wiki
Jump to navigation Jump to search

Modding, or creating mods, is the act of modifying the behavior of the base game (often referred to as vanilla), either for personal use, or to release publicly for other players, for instance - via the Steam Workshop.

As for all Paradox games, Hearts of Iron IV is moddable to a great extent. Motivations of modders may vary widely: a better translation to their native language, more events or decisions, better maps, a major overhaul, etc.

By default, mods for Hearts of Iron IV are located in these folders:

  • Windows: C:\Users\<Username>\Documents\Paradox Interactive\Hearts of Iron IV\mod
  • Mac OS: ~/Documents/Paradox Interactive/Hearts of Iron IV/mod
  • Linux: ~/.local/share/Paradox Interactive/Hearts of Iron IV/mod

To start modding, you will want to create a mod structure in the mod directory.


  • Never modify game files: use a mod even for small changes, and never modify directly game files in Steam Hearts of Iron 4 folder, as your changes may be undone without warning.
  • Use a good text editor (like Notepad++ or Sublime Text) to edit files and search into multiple files.
  • Minimize overwrites of vanilla files by adding separate files and loading from folders whenever possible, to improve mod compatibility and maintenance. (Your files can have any name, all files in the folder will be loaded by the game. So choose a name, no one else will ever use, like the name of your mod. Ex: coolmod_countries)
  • Use a proper merge tool (like WinMerge), to merge between folders, and update modified vanilla files to a new vanilla patch.
  • Backup your work to avoid losing everything. Consider using a source control system like Git and a collaborative forge like GitHub to manage team collaboration, or just make a copy of the file somewhere else.
  • Use UTF-8 encoding for text files.
  • Use UTF-8-BOM for localisation files (.yml).
  • Indent properly to easily spot unclosed braces. Vanilla uses 1 tab for indentation rather than spaces.
  • Use comments starting with # character, to remember reasons for writing tricky stuff.
  • Debug effectively by enabling Debug mode. Do this by adding -debug to your launch options in Steam. This will enable verbose error logging.

Mod Structure[edit]

Game mods are located in:

  • Regular \Paradox Interactive\Hearts of Iron IV\mod\
  • Steam Workshop: \Steam\steamapps\workshop\content\394360\

The name of the .mod file must not contain any spaces, or it will not be auto-selected by the game launcher.

There are three main classes of mods that pertain to the structure of the .mod file. These classes are Minor Mod, Major Mod, and Submod and the general structure of these mods is shown below. It is up to the maker of the mod whether or not the mod should be considered a minor, major or sub-mod.

Mod Thumbnail[edit]

Since the release of the "new launcher" all thumbnails must be named "thumbnail.png" and located in the root folder of your mod.

Minor Mod[edit]

The most common type of mod is a minor mod, or a mod that changes only a small part of the game. These types of mod don't need new savegame or graphics folders as and so do not need to use user_dir nor replace_path in order to keep compatibility with other small mods.

 name = "Minor Mod"
 path = "mod/MinorMod"
 picture = "thumbnail.png"
 tags = { "Minor" "Mod" }

Major Mod[edit]

Major mods can typically be divided into two categories, though can - and often do - overlap. These are Overhauls and Total Conversion Mods. Overhauls use user_dir due to the fact that saves cannot be loaded outside of the mod. For Total Conversion mods, replace_path can be used to completely ignore vanilla directories that don't make sense in the context of the mod (history, flags, ...).

 name = "Major Mod"
 path = "mod/MajorMod"
 user_dir = "MajorMod"
 replace_path = "history/states" 
 picture = "thumbnail.png"
 tags = { "Major" "Mod" }

Sub Mod[edit]

Submods of a major mod can use dependencies to be able to more precisely override files from main mod. This is necessary for the submods to operate as intended.

 name = "Sub Mod"
 path = "mod/SubMod"
 dependencies = { "Major Mod" }
 picture = "thumbnail.png"
 tags = { "SubMod" "Major Mod" }

Game data[edit]

Names for in-game items (e.g. the name for research categories or rules like can_create_faction) can be found in the game's localization folder, inside the localization files.

Image file formats[edit]

Use DDS format for images. Most of the files are saved in ARGB, 32 bit unsigned sub-format. Some files (like leader portraits) are saved using ARGB 16 bit unsigned variant. Event Image can also be of the .tga format. Flags are saved as 32bpp .tga files.

Tools & utilities[edit]

See also[edit]