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, the user directory for Hearts of Iron IV is located in the following folders:

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

Mods are stored within the mod/ folder within the user directory. If the path to the user directory (Including the Windows username) includes any special characters (Such as umlauts, other diacritics, or Cyrillic), the game will not work properly. Local mods will fail to load, and the game will not be able to open the error log by itself. The user directory's location can be changed in /Hearts of Iron IV/launcher-settings.json in the base game folder by changing the "gameDataPath" line and moving the files to that folder.

Alongside mods, the game will load any files stored in the user directory. The game's internal map editor, the Nudger, stores its output within that folder.

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

Guidelines[edit | edit source]

  • 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 to edit files and search into multiple files. The following are free:
    • Notepad++. Choose Perl as your language, as it will provide good highlighting and allow to fold blocks of code and comments. To set it as default, go to Settings, Style Configurator, find Perl in the list on the left and add "gui txt" (without quotes) to the "User ext." field at the bottom.
    • Visual Studio Code. Has a fan-made CWTools extension with Paradox syntax highlighting, validation and tooltips for triggers and effects. To install it, go to Extensions on the left panel of VS and search for CWTools. (Note: validation rules are incomplete and will show many false errors in gui and localization files).
    • Sublime Text. There is an extension for it released by the developers of Imperator which could be used with HOI4 but use at your own risk: Sublime Tools. It adds colored highlighting for effects and triggers. If you want to toggle comments in Sublime, you also need to add this file to the same "User" folder.
  • 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. The launch options are accessed in the menu opened by right-clicking the game and choosing 'Properties..'.

Advantages to using debug[edit | edit source]

  • Automatic loading - Edits to files done inside the mod folder will show up in-game without the need to use the 'reload' console command. This will also automatically add the errors in the files to the error log. This only applies to files that existed when the game was launched, with an exception: if a file's direct path gets mentioned elsewhere within the mod, then it can still get loaded for that use in particular. Examples of that include orders of battle, as load_oob = "TAG_my_oob" functions as a direct link to /Hearts of Iron IV/history/units/TAG_my_oob.txt; or GFX, as sprites directly reference the position of the image. Although, notably, the loading of images in-game does not uncompress them properly, leading to visible distortion or black backgrounds which get fixed on a restart. Although edits to most files work, this doesn't work with /Hearts of Iron IV/history/countries/, /Hearts of Iron IV/history/states/, and /Hearts of Iron IV/map/, although the nudge partially can be used for the latter two.
  • No map definition crash - If the map is edited, there's a possibility for errors to appear. Any map-related errors will crash the game when loading with a message saying 'Some errors are present in the map definition and have been logged to error.log'. If debug mode is on, the game will continue to load properly. The map definition occurs when there is any error containing MAP_ERROR within the error log after loading into a country.
  • Extended error log - Certain errors do not get logged in the log unless the debug mode is turned on. An example would be the map definition errors mentioned above, as the game crashes before getting a chance to log them. Enabling debug mode will ensure that all errors that can be logged in the error log will get logged.
  • Ease of error log opening - As long as there are any errors in the log, the log will automatically open when loading the game or after selecting a country. The log will also be able to get accessed by clicking on the error dog in the bottom-right corner after loading into a country, which appears each time a new error appears in the log (since files get automatically loaded-in).
  • Ease of nudge access - With debug mode turned on, an option to open the nudge will appear in the main menu. This can be useful to save time or to be able to open the nudge if the game crashes when you're trying to load into a country (This can happen if the /Hearts of Iron IV/tutorial/tutorial.txt file references invalid states, if that file doesn't contain at least one tutorial = {} even if not containing anything, if supply nodes and railways aren't set up properly, or for other reasons).
  • Graphical interface information in the main menu - As long as the debug mode is turned on, hitting the ` button (Typically in the top left corner of QWERTY keyboards, used to open the console by default) in the main menu will provide information about the graphical interface used, giving the names of elements, their positions, and the sprites used by them. This is equivalent to using the "gui" console command, but the debug mode makes it possible to do in the main menu.
  • Expanded province info - With debug mode turned on, there will be additional information when hovering over the province, including its and the state it's in's IDs, tags of owner and controller, et cetera.
  • Access to more console commands - Certain console commands are locked for developers only and debug mode allows the player to use them. However, note that not all console commands will become available.
  • Ease of access to GUI files - When hovering over a GUI element, Ctrl+Alt+Right Click can be used to open a debug menu, which will allow going to the GUI file where the element is defined.
  • Automatic saving on peace deals - The game automatically creates a savefile each time a peace conference occurs with debug.

Note that if you turn on the debug mode through the 'debug' console command, only the last 4 advantages will be available to use. If debug is turned on via launch options, be that -debug or -crash_data_log, all benefits will be granted.

Universal modding concepts[edit | edit source]

  • It's heavily recommended to turn off Windows file explorer from hiding file extensions from the filename, if using Windows. File extensions are considered a part of the filename, and hiding them can cause files to not work due to wrong filenames (Such as accidentally saving localisation files as .txt files, saving an image in the wrong format and not realising it, et cetera)
  • After creating a mod folder within the launcher, every single file within will get loaded at the same order as in base game. Taking a mod with the name of "yourmod" as an example, every single file within mod/yourmod/common/national_focus will get loaded alongside files in base game's /Hearts of Iron IV/common/national_focus, however, if you insert one more folder as in mod/yourmod/test/common/national_focus, these files will not get loaded. The root folder of the mod, considered the same as the /Hearts of Iron IV/ folder in base game, will be defined in the user directory's /Hearts of Iron IV/mod/yourmod.mod file, opened with a text editor, within path = "", by default being /Hearts of Iron IV/mod/yourmod/.
  • The game loads files in the order of base game, then DLCs (within the /Hearts of Iron IV/dlcs/ folder), then user directory, and finally mods. The mods are usually loaded in the order specified in /Hearts of Iron IV/dlc_load.json file within the user directory, which is the same as the order in the launcher. If there's a file with the same name in the exact same folder between these (For example, both /Hearts of Iron IV/events/AcePilots.txt and mod/yourmod/events/AcePilots.txt), the game will only read the one that is later in the load order, ignoring all contents of the previously-defined one.
  • Other than the overwriting of files with the same name above, filenames don't matter at all in how the file is read with few exceptions. For vast majority of files, they're either read only by the virtue of being within a specific folder (Such as national focuses), or by a direct link within a different file (Such as oob = "TAG_1936" within a country history file loading the /Hearts of Iron IV/history/units/TAG_1936.txt file for unit locations). Due to this, it's usually recommended to avoid overwriting base game files when adding new content that doesn't need to overwrite base game files as to make future-proofing of the mod for game updates better.
  • Names depending on language are defined within localisation. Taking the English language into consideration, /Hearts of Iron IV/localisation/english folder is used. A file within must end with _l_english.yml in the filename to work properly. The file must be encoded in the UTF-8 encoding with the byte-order mark included, usually called UTF-8-BOM. The exact details on conversion depend on the text editor, but it's usually within the topbar or bottombar.
A localisation entry is structured as localisation_key:0 "Value of the key". In here, the first part before the colon is referred to as the localisation key, the ending part in quotes is referred to as the localisation key's value, and the number in-between is the version number. The version number is purely a comment and isn't read by the game, it's possible to be omitted entirely. Any localisation file can be used for any localisation, and it's better to use new files rather than copying over base game files.
  • Almost every single image is defined within /Hearts of Iron IV/interface/*.gfx files, opened within a text editor. A simplest sprite definition is the following:
spriteType = {
    name = GFX_my_sprite_name
    texturefile = gfx/interface/folder/
This assigns the /Hearts of Iron IV/gfx/interface/folder/ file to have the GFX_my_sprite_name sprite in-game, so using GFX_my_sprite_name as an image will link back to that file. This is necessary to do because there are more potential arguments that may go into sprites, such as the amount of frames and animations. The only images that do not have any definition within interface files are:
  • Flags used for countries in /Hearts of Iron IV/gfx/flags/ and its subfolders.
  • Loading screens within /Hearts of Iron IV/gfx/loadingscreens/. Note that, however, the main menu background usually stored in that folder is defined as a sprite.
  • Character portraits. They may use a sprite as a definition, but they're the only place in the game which doesn't have it as a mandatory requirement, accepting direct links to the file as an alternative.
  • At times, it can be helpful to know how to search every single file within a given folder: if an error doesn't give the folder it comes from, needing to modify an existing localisation key or to find where the image is stored knowing the sprite's name. This can be done within most text editors. Previously-recommended Notepad++, Sublime Text, and Visual Studio Code each use the Ctrl+Shift+F hotkey for this tool.
This can be used in combination with the gui console command (Or its main menu equivalent) in order to find out the file of a certain image. Hovering over any interface element can grant information about it: its sprite, always beginning with GFX_, and the name of the element in the interface file. Searching every file within the interface folder at the same time can find the *.gui file where the element is defined (Such as to change the position, the font, and/or the sprite used by it) or the *.gfx file where the sprite is defined (In order to find the image file which stores it).

Mod Structure[edit | edit source]

Game mods are located in:

  • Regular Documents\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. Mods, alongside a file in Documents\Paradox Interactive\Hearts of Iron IV\mod\, contain descriptor.mod in the root directory of the folder. The descriptor must be the same as the *.mod file in the 'mod' folder but without the path. If you add something in the ModName.mod file without adding it to the descriptor, such as a replace_path, it will be automatically deleted.

Mod definition[edit | edit source]

A simple *.mod file will have something like this:

name = "Minor Mod"
path = "mod/MinorMod"
picture = "thumbnail.png"
version = "v1"
supported_version = "1.11.*"
  • name is the name of the mod in the launcher.
  • path is the location of the mod folder. A shortened path, without Documents/Paradox Interactive/Hearts of Iron IV/ will work, making the game automatically generate a new one. The path does not have to lead to the documents folder, path = "C:/folder/modname" will also work as long as the mod is in that folder. Note that if the path contains any special characters, including but not limited to Cyrillic, the mod will not work. Alongside that, a backslash, or \, will not work to separate folders in the path, only / will work.
  • picture is the picture of the mod, located in the root directory. It must be named "thumbnail.png" to work correctly.
  • version is what the launcher will show as the version of the mod (Not the version of the game it's meant for). Any string is accepted.
  • supported_version is used to determine for which version of the game the mod is meant for.
  • tags are tags with which the mod will get marked upon getting uploaded to Steam Workshop.
  • remote_file_id is added by the launcher upon uploading the mod to Steam Workshop. It is used to assign the workshop item to the mod.

Some other additional arguments can be used as such:

 user_dir = "MajorMod"
 replace_path = "history/states" 
 dependencies = { "Major Mod" "Major Mod 2" }
  • user_dir changes the folder where the mod's saves are stored. This can be useful so that the mod's saves can not get mixed up and accidentally loaded without the mod on and vise-versa.
  • replace_path makes every file that was already loaded in the specified folder beforehand get unloaded when starting to apply changes from this mod. For example, replace_path = "history/states" will unload every state that gets loaded prior to this: base game, user directory, and other mods (depending on the mod load order). This will ensure that no base game states will be loaded in the mod. Note that replace_path does not overwrite the subfolders within the specified folder. The launcher frequently fails to port this option to the modname.mod file, so it should be added to both mod/modname/descriptor.mod and mod/modname.mod manually.
If a file only gets loaded after the main menu is loaded, a replace_path will not unload it. For example, a replace_path = "history/units" has no effect since the files in that folder aren't loaded before the main menu loads, but are instead loaded directly via the load_oob = "filename" effect or the oob = "filename argument in country history. Meanwhile, replacing history/countries would work, since the game loads every file before the main menu finishes loading, but only executes effects in them later on. This also applies to gfx/flags: replacing that folder has no effect.
This can be seen by a replace_path to gfx/loadingscreens. Doing so will remove the base game's loading screens from being possible to be picked by the game. However, the main menu background - since it is defined in /Hearts of Iron IV/interface/frontendmainviewbg.gfx where it only gets loaded after the main menu loading finishes, when getting to the main menu - will remain the same as in base game.
  • dependencies makes the current mod be placed higher in load order than the specified dependencies. This will ensure that the mod will overwrite the specified mods' contents: if there is overlap between the files of this mod and a dependency, this mod's files will be chosen. This also ensures that the dependencies' replace_path will not unload any files from this mod and, vise versa, each replace_path in this mod will unload files from the dependencies. Despite its name, the mod which is marked as a dependency is not necessary to be turned on for this mod to get loaded. This is necessary for sub-mods to work correctly.

Game data[edit | edit source]

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.

Checksum[edit | edit source]

The checksum is the 4-letter code that can be seen in the main menu. If the checksum is different, ironman mode won't give achievements. Alongside that, in multiplayer you can only join servers with the same checksum.

Editing most files will edit the checksum, but not all of them. The files that edit the checksum are

  • Everything in common, history, and events folders
  • In map folder, everything but map/terrain.

Thus, translations, SFX, GFX, music, and etc can be changed without preventing the ability to get achievements or join multiplayer with a server that doesn't have that mod.

Image file formats[edit | edit source]

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 the ARGB 16 bit unsigned variant. Event Image can also be of the .tga format. Flags are saved as 32bpp .tga files.

Tools & utilities[edit | edit source]

Useful knowledge[edit | edit source]

If there are 2 mods with the same name in the launcher, say, if you subscribe to your own steam mod while still having it in local files, the one that was added later will not work. This can be fixed by changing the name of either one of the mods.

Large English-speaking modding communities include the HOI4 Modding Coop and the HOI4 Modding Den, which can be joined on Discord. It's useful to join one or multiple of them, as they contain links to modding resources and you can ask questions regarding modding in them.

settings.txt, located within the user directory also containing the mod folder, can be changed to change the game uses to open files from Microsoft Notepad, if the path to the editor is correct. Here are examples with 2 of frequently used text editors:


editor="C:\\Program Files\\Notepad++\\notepad++.exe"
editor_postfix=" -n$"

Sublime Text:

editor="C:\\Program Files\\Sublime Text 3\\sublime_text.exe"

See also[edit | edit source]

References[edit | edit source]