Modding

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

• 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.
• 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 or Gitlab to manage team collaboration, or just make a copy of the file somewhere else. Version keeping via Github or Gitlab can also be very useful for debugging due to limiting the selection of potential broken files.
  • The Modding Git Guide is a community made guide for using Git, GitHub/GitLab, and related tools such as KDiff3. It can be a useful stop for questions beyond this wiki, and contains step by step guides for much of what is talked about here.
• Use UTF-8 encoding with the byte order mark for text files. This is commonly called "UTF-8", but can sometimes be specified as "UTF-8 without BOM".
• Use UTF-8 encoding with the byte order mark for localisation files (.yml). This is commonly called "UTF-8-BOM", but can be just "UTF-8", in which case omitting the byte order mark is a separate option. Some text editors, such as Atom, do not support the byte order mark in entirety and should be avoided for localisation.
• Use comments starting with # character, to remember reasons for writing tricky stuff. A single sharp sign will make the rest of the line completely ignored. There is no multi-line comment notation in the code.
• 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..'.
  Alternatively, in Windows it's possible to create a shortcut to the hoi4.exe or dowser.exe file, and then to open the shortcut's properties and append -debug (separated by a space) after the path's end, such as "C:\Program Files (x86)\Steam\steamapps\common\Hearts of Iron IV\hoi4.exe" -debug.

Debug advantages

• 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.

Text editor

These are the most common text editors to use for modding the game:

• 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).

Recent versions with automatic highlighting of {} pairs in different colours and flagging opened/closing ones that are missing a partner red is worth it's weight in gold.

• 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.

Some options that are commonly turned on by default in other text editors are turned off in Notepad++, but can be changed in the topbar. This includes Word wrap, Document map, Indent guide, and Folder as workspace.

• 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.

Reasons to use a non-default text editor include the following:

• Bracket and syntax highlighting. Bracket highlighting makes it easier to detect any missing or unnecessary files by allowing to select a bracket and see where it opens or closes, as to know what's inside of that block. Syntax highlighting can make code more easily readable by highlighting more important parts, as well as excluyding brackets within comments from being considered such.
• Searching in multiple files in the same folder. In each provided tool, this is activated with the ^Ctrl + ⇧Shift + F hotkey and can have filename filters in order to limit the files that are searched (e.g. *.txt will only search text files, ignoring any other files, such as *.dds ones).
• Each line is numbered on its side. Since error log typically points to the line where an error is present, this makes finding the line in question much faster compared to how the Microsoft Notepad only tells the number of the currently-selected line in the below.
• Greater capabilities to work with multiple files. Each of these editors may only have one instance of it open at a time with multiple files open at once (switching between them with ^Ctrl + ⇆Tab), in contrast to Microsoft Notepad that opens a separate instance for each opened file, which can quickly fill the Alt + ⇆Tab menu. Multiple instances of the text editor can still be opened, however. A text comparison tool also exists on each one of these: "ComparePlus" plugin in Notepad++, "Compare Side-By-Side" or "Diffy" package in Sublime Text, or a variety of Visual Studio Code extensions ("Partial Diff" being the most popular one).
• Greater customisation capabilities: each of these text editors allows a wide variety of light or night themes that can be picked as fit, with downloadable themes existing as well. Since one would need to look at the text editor a lot while modding, selecting a theme that looks good to the eyes can make the experience much better.

Searching multiple files

One feature of non-default text editors is a highly-customisable search of all files within the same folder. This is highly useful for dealing with errors and finding locations of certain elements. This is how exactly the feature is enabled in the common text editors:

• Notepad++ – This is located in the "Search" topbar menu as "Find in Files...". By default, no folder is provided. "Follow current doc." allows the text editor to automatically input the currently-opened document's folder as the place for the search, or it can be entered manually. Alternatively, this menu can be opened from the right-click menu of a folder within the "Folder as Workspace" menu – accessed by a button in the topbar – which'll automatically set the folder location to be that folder. The ^Ctrl+⇧Shift+F hotkey also opens the menu for this feature by default.
• Sublime Text – This is located in the "Find" topbar menu as "Find in Files...". In order to add a folder to search, the menu to the right of the "Where:" line can be opened, with either "Add Folder" (to select an individual folder) or "Add Open Folders" (To automatically select all folders opened via Sublime Text) buttons serving to do so. The ^Ctrl+⇧Shift+F hotkey also opens the menu for this feature by default.
• Visual Studio Code – Visual Studio Code only supports searching the currently opened folder. A folder is opened either through the "Open Folder..." button in the "File" topbar menu or the "Explorer" menu, accessed through the bar on the left. After this, the functionality can be accessed in the "Edit" menu as "Find in Files". In order to speed up the search, filename filters can be used. For example, localisation/english/*.yml within "files to include" will only search every *.yml file within the <currently opened folder>/localisation/english/ folder, where * stands for any amount (including 0) of any characters within the filename. Similar filters can be used in the previous two text editors, however without allowing folders to be filtered — only the filenames. The ^Ctrl+⇧Shift+F hotkey also opens the menu for this feature by default.

A filter on the file extension can be set to speed up the search. This depends on the text editor. Note that * is used to mark any amount of any characters, and this is universal.

• In Notepad++, this is done with the 'filter' menu. Filters are separated with spaces, and an exclamation point in the beginning marks it as an exclude filter. For example, *.yml !*french.yml will result in searching every localisation file aside from the French ones.
• In Sublime Text, this is in the 'where' menu. Filters are separated with commas, and a minus sign in the beginning marks it as an exclude filter. For example, C:\Program Files (x86)\Steam\steamapps\common\Hearts of Iron IV\, *.txt, -GER* will search every text file in the base game (Assuming the default location within Windows on Steam) with the exception of those that begin with GER.
• In Visual Studio Code, this is in the menu triggered with the 'Toggle Search Details' button, represented with an ellipsis. This menu has separate "Files to include" and "Files to exclude" menus, used accordingly. Additionally, this allows representing folder names within the menus, with the doubled * (as in **) used to represent an arbitrary folder name. For example, *.gfx in the "Files to include" and dlc/** in "Files to exclude" will search every single file with the .gfx extension with the exception of those in the dlc folder.

There are the following uses for this:

• Finding out an internal ID by searching the localisation folder for the localised name. For example, searching for an event's title can be used to determine the ID.
• Finding out where the database entry of a certain type is defined where it is not immediately intuitive. For example, by searching for an equipment ID within the folder that stores equipment (or even /Hearts of Iron IV/common/ in general) can be used to find the exact file, which isn't immediately obvious for some equipment types.

A subset of this includes finding sprites' or interface elements' locations: The gui console command (or its main menu equivalent in debug mode) can be used in order to find the name of a certain SpriteType (prefixed with GFX_) or interface element. A search query with the given name within the /Hearts of Iron IV/interface/ folder will provide the file where the sprite is defined (as such, also giving the texturefile that says the path of the image in gfx) or the interface folder (which allows copying it to the mod and editing it).

• Dealing with unintuitive errors where the location is not specified, such as Invalid Decision Category, where this can be used to locate which file is throwing the error.
• Finding out what can cause a certain occurance to happen, such what fires a certain event.

Indenting

Another reason to use non-default text editors is greater indenting capabilities. Indenting refers to the usage of newlines and spaces at the beginning of the line, which does not leave an impact on how the code is interpreted, but makes it easier to see the relations between different parts of the code.
Typically, either a tab character (represented as \t) or 4 spaces are used as a single indenting level, placed from the beginning of the line to the beginning of code on the line. In order to increase the indenting level of code, the ⇆Tab button is used in text editors, which can be done on multiple lines at the same time by selecting them. Inversely, ⇧Shift+⇆Tab is used to decrease the indenting level of the line by one.

An additional option present in these editors is 'Indent guide', drawing a line on each indent level in order to make it easier to see the borders of each indent level, which can assist in code capability. While turned on by default in Sublime Text and Visual Studio Code, this must be turned on manually in Notepad++ within the topbar.

These are the typical conventions used for indenting:

• The first line of the file has zero indenting.
• An opening bracket and its corresponding closing bracket must be placed on lines with the same indenting level.
• If a line introduces an unclosed opening bracket, then everything until the proper closing bracket must be one indent level to the right compared to the line with the opening bracket.
• A line shouldn't have more than one bracket of each kind.

This is an example of proper indenting:

TAG = {
    if = {
    |    limit = {      # The bar character "|" is used to visualise the indent guide, rather than being used in-code.
    |    |    has_stability > 0.5
    |    |    has_war_support > 0.5
    |    }
    |    country_event = { id = my_event.1 hours = 1 }
    }
}

Proper indenting has two primary benefits:

• It's easy to where an argument is contained by moving one indenting level to the left and then following the indent guide's line until it hits code.
• It's easy to find what falls within a block by following the indent guide's line from the line with the open bracket to the point where it hits the closing bracket.

Some common errors to check for in the indenting are the following:

• Putting 2 closing brackets on the same level:

if = {
    limit = {
        my_scripted_trigger = yes
    }
    } # Closes the if statement, and so should've been one more level to the left to match the if statement's indent level.
    my_scripted_effect = yes # Always executed due to being outside of the if statement.
}

• Placing neighbouring lines with a difference of at least 2 indent levels:

focus = {
    <...>
    completion_reward = {
        TAG = {
            country_event = my_event.1
    } # Closes TAG = { ... }
}     # Closes completion_reward = { ... }
focus = { # Does not work due to being contained within another focus = { ... }
    <...>
}

Following the indenting rules and checking for these indenting errors will ensure that there will be no bracket-related errors within the code.

Universal modding concepts

• 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, the mod's national focus 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. This is set via path = "" in that file, by default being user directory's /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 set by the names of their mod files. 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. The base game utilises this to change the main menu background by changing the /Hearts of Iron IV/interface/frontendmainviewbg.gfx file within each DLC and this is also a primary foundation by which mods work.

In other words, if not specifically set to unload files in the same folder with replace_path, every single base game file will get read within mods unless there's a file with the same name in the same folder within a DLC, the user directory, or an enabled mod's files, in which case the priority will be established in that order.

Note that the files are not immediately interpreted once they are loaded (with the exception of localisation), instead the interpretation happens after every file that needs to be loaded is already loaded. For the vast majority of folders, such as /Hearts of Iron IV/interface/*.gfx or /Hearts of Iron IV/common/ai_peace/*.txt files, the ASCII character IDs are used to sort. This is different from the alphabetic sorting used by the file explorer as uppercase letters are considered earlier than lowercase letters and there are multiple characters inbetween (such as underscores) that are later than uppercase letters, but earlier than lowercase letters. In order to place a file particularly high in the evaluation order, you can make the name begin with a lowercase zzz_ prefix. Meanwhile, /Hearts of Iron IV/history/countries/*.txt files are interpreted in the order that the tags are defined within /Hearts of Iron IV/common/country_tags/*.txt files (which use the same ASCII character ID order).

Changing the interpretation order has very limited use, but it is present, such as with AI in peace deals where the AI only picks the first-loaded AI or with interface, as when encountering contradictory definitions of an interface element (whether it's a spriteType, a containerWindowType, or something else), the game chooses the one defined later. The base game primarily uses it for sprites that point to different images depending on the DLC, such as portraits included with DLCs which point to a generic portrait without that DLC.

• Other than the overwriting of files with the same name and setting the interpreting order 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.
• Comments are marked with the # character: everything after that character until the newline will be entirely ignored by the game.
• Aside from comments and strings (marked with the quotation marks, must be on one line total), indenting does not matter: most files can be done on one line in total without breaking. However, doing indenting properly can make detecting bracket problems much easier without using a text editor's bracket highlighting and overall makes it easier to see at a glance what each block (marked with the figure brackets as block_name = { ... }) includes within of itself and what it doesn't.
• 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.

While it is possible to avoid using localisation in many cases, it is better to not do so for the following reasons:

• Special characters, such as umlauts and other diacritics. Multiple files such as country leader traits or adjacency rules provide no support for the UTF-8-BOM encoding, which allows to use special characters within of themselves, and so using them in the name will be impossible.
• Multiple language support. Even if desiring the mod to only be within English or a different language, it is better to allow the option to be open for potential sub-mods. While it is still possible to make translation sub-mods to mods that don't use localisation, it becomes much harder to keep it up-to-date (As more than just localisation files can be changed in this case) and changes the checksum (Making it impossible to have a multiplayer session between those that have the translation sub-mod and those that don't).
• Dynamic localisation. In a large portion of files, such as scripted localisation, the name argument or any alternative is strictly expected to point towards a localisation key, just displaying the name of the key if not finding one. That means that any localisation commands such as newlines, coloured text, and namespaces cannot be used.

• Almost every single image is defined within /Hearts of Iron IV/interface/*.gfx files, opened within a text editor. A simplest sprite definition, within a spriteTypes = { ... } block encompassing most of the file, is the following:

spriteType = {
    name = GFX_my_sprite_name
    texturefile = gfx/interface/folder/filename.dds
}

This assigns the /Hearts of Iron IV/gfx/interface/folder/filename.dds 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.

There are also potential errors that may occur related to sprites:

• A sprite is entirely transparent: This is an indication that the sprite exists, but the image within can't be loaded. This occurs if the texturefile is defined to a file that doesn't exist (Commonly because of a typo either within the filename or the texturepath) or if the image itself is corrupted. This is usually accompanied with a Texture Handler encountered missing texture file error.
• A sprite is replaced with the default image: This is an indication that there is something wrong with the sprite itself rather than the image: the game links to a non-existing sprite somewhere. This is typically a typo within the sprite's name or a failure to follow a name format (Such as omitting _shine from the end of a national focus icon's shine sprite). Ensure that the sprite exists and has the right name.
• The character uses a randomly-generated portrait: This is an indication of either of the previous two problems: a character with an invalid sprite or a missing file will have their portrait randomised.

Mod structure

Each game mod has a definition within the user directory's /Hearts of Iron IV/mod/ folder as a *.mod file. This tells the game what settings to assign this mod and where exactly is the folder that stores it. Since the *.mod file format is also used for videos, the computer might think that this file is to be opened with a media player, but this is not the case: it is to be opened with a text editor.
Each mod has two *.mod files, the /Hearts of Iron IV/mod/*.mod file and the descriptor.mod file directly within the root folder of the mod, specified within path = "" of the former. The descriptor says what the /Hearts of Iron IV/mod/*.mod should have, and so these two *.mod files should be identical with the exception of the folder path which should only be in the /Hearts of Iron IV/mod/*.mod file as this depends on the machine. This is indeed monitored by the launcher: anything within the former /Hearts of Iron IV/mod/*.mod file that's not within the mod's descriptor.mod will be automatically deleted when the launcher gets opened. However, the inverse is not automatically true: the launcher periodically fails to carry over descriptor's arguments to the /Hearts of Iron IV/mod/*.mod file. An argument will only be executed if it's in the /Hearts of Iron IV/mod/*.mod file as it is what the game uses, so to be safe it is best to manually edit both descriptor.mod and /Hearts of Iron IV/mod/*.mod when needing to change a mod's definition.

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

Mod definition

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

name = "Minor Mod"
path = "mod/MinorMod"
picture = "thumbnail.png"
version = "v1"
supported_version = "1.12.*"
tags={
	"Gameplay"
	"Historical"
}
remote_file_id="<ID>"

• 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. In addition, thumbnail files should be less than 1MB in size, otherwise they cannot be uploaded to ParadoxMods.
• 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, granting the 'out of date' marker in the launcher otherwise. The last number of the version can be replaced with an asterisk in order for the mod be considered up to date for any version within the specified major update.
• 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 and indexed 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. Additionally, 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 because flags aren't loaded and indexed during the main menu background, but only after selecting singleplayer, interpreting history for each country. This can be seen by when the "file not found" errors appear for missing flags: only after the loaded history files get interpreted by the game.

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

• Console commands, useful for debugging mods.
• Defines, which allow to influence some hardcoded vanilla behaviors
• Scopes, Triggers, and Effects used for scripting
• Modifiers, used to influence calculations made by the game
• Event modding, used to define popups with decisions

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

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

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

Tools & utilities

• Official Paradox Forum for mods
• Maya exporter - Clausewitz Maya Exporter to create your own 3D models.
• Steam Workshop - The place where you can share your creations with other players.

Common mistakes

• Two mods with the same name (Mod fails to load) – This commonly happens when subscribing to one's own mod on Steam Workshop. If there are two mods with the same name, the game will fail to load the one that was added later, making it appear as if the base game was opened. This is corrected by changing the name of either of the mods.
• Wrong path (replace_paths apply, yet the mod doesn't get loaded) – In this case, the needed file to adjust is /Hearts of Iron IV/mod/modname.mod, opened directly within a text editor. There are two primary variations on this issue:

• Incorrect path – This is commonly the cause if the game displays the filesize of the mod, but doesn't load it. The mod doesn't route to the file directly. This can sometimes be a cause of further subfoldering, such as if the mod is located in mod/my_mod/cool_mod, yet the machine-specific .mod file contains path = "mod/my_mod". In this case, the files still exist and get loaded. However, the game, for example, expects focus trees in the /Hearts of Iron IV/common/national_focus/ folder. mod/my_mod/cool_mod/common/national_focus/ gets taken to be /Hearts of Iron IV/cool_mod/common/national_focus/ instead, as path = "mod/my_mod" doesn't knock off the /cool_mod/ folder. This is corrected simply by adjusting the path to be to the correct folder.
• Impossible path – The intended folder is correct, yet it's stated in a way that the game can't recognise.

One of the ways of doing so is using backslashes for folder separations, such as path = "mod\my_mod". This is incorrect, as a single backlash gets taken to be an escape character instead. Using forward slashes as in path = "mod/my_mod" is correct.

Another way of doing so is using special characters in the name, such as path = "C:/Users/Пример кириллицы/Documents/Paradox Interactive/Hearts of Iron IV/mod/my_mod". In this case, a special character is defined as one that takes more than 1 byte to write with UTF-8, not being present in ASCII's printable characters. This is commonly non-English language folder names, such as diacritics or non-Latin alphabets. In this case, it can be rerouted to a folder that does not contain special characters in the name, such as path = "D:/Hearts of Iron IV modding/my_mod". If the path to the user directory itself contains special characters, it's better to re-route the entire directory to another folder. To do so, edit the base game's /Hearts of Iron IV/launcher-settings.json file and change the folder specified under gameDataPath. After doing so, move the user directory's contents to that folder as to not lose save games and other information. The mod's path also needs to be adjusted properly. If the user directory is located at an impossible path, the game will also fail to open the error log with debug turned on with a "The system cannot find the path specified" error.

• Incorrect dependency name (Mod fails to loaded when enabled with the main mod) – If a mod is intended to be a sub-mod to a larger mod or several, it is, in most cases, mandatory to include dependencies = { "Main mod 1" "Main mod 2" }, which will place it higher in the load order. In this case, the name of the mod must be the exact same as in the .mod file of the mod, also showing up in the launcher. This can include special characters (e.g. name = "Main mod – Subtitle" in the main mod will require dependencies = { "Main mod — Subtitle" } in the sub-mod with an en dash rather than a hyphen). For this reason, it's preferable to copy over the name from the .mod file of the main mod rather than manually retyping it from the launcher: some special charactes may be difficult to notice or to distinguish from other characters.
• Not copying over mod information entries (Entries such as replace_path fail to apply) – The game keeps the mod's modname/descriptor.mod file as the information for the mod in general and /Hearts of Iron IV/mod/modname.mod as the information for the mod that gets read for the machine. While the launcher typically attempts to keep the machine-specific file up to date with the general mod information file, it sometimes fails to do so, such as for replace_paths where it succeeds at deleting unneeded entries but not at copying needed ones. In this case, both files must be edited manually for a replace_path to apply. This also may be needed for other entries in the file.
• Files with similar names (File gets loaded twice) – In this case, "similar" is defined as a pair of files within the same folder that have names made up of different characters, but would be considered as having the same name with case-insensitive checking, such as /Hearts of Iron IV/events/Generic.txt and /Hearts of Iron IV/events/GENERIC.txt. If the mod files contain a file that has a similar name to a base game file, the mod file will get loaded twice. Adjusting the filename to be the exact same as the base game file or entirely distinct will fix this issue. This applies even if the folder that the base game file is in is unloaded with replace_path.

Useful knowledge

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:

Notepad++:

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

Sublime Text:

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

See also

• Mods
• Getting started with modding forum: 995985
• How to create a new ship unit in Man the Guns forum: 1157324
• How to add a new unit - Checklist forum: 947435

Notes

^ a: These exceptions that may reasonably be changed within a mod are the following:

• /Hearts of Iron IV/gfx/flags/ and its subfolders, where the name must follow a strict formatting in order to be automatically loaded for a country.
• /Hearts of Iron IV/history/countries/, where the first 3 letters assign it to a country.
• .txt files directly inside of /Hearts of Iron IV/common/ (Most importantly achievements.txt, combat_tactics.txt, and graphicalculturetype.txt)
• /Hearts of Iron IV/common/countries/colors.txt and /Hearts of Iron IV/common/countries/cosmetic.txt must remain with the same name. The rest are directly linked to in /Hearts of Iron IV/common/country_tags/*.txt files.
• A variety of items within gfx such as /Hearts of Iron IV/gfx/maparrows/maparrow.txt or /Hearts of Iron IV/gfx/HOI4_icon.bmp. This does not include /Hearts of Iron IV/gfx/loadingscreens (every file within there is loaded regardless of filename) or most font/image files (as they're loaded by a link within a different file).
• Files within the /Hearts of Iron IV/map/ and /Hearts of Iron IV/map/terrain/ folders, with the exception of /Hearts of Iron IV/map/strategicregions and those defined within /Hearts of Iron IV/default.map.
• /Hearts of Iron IV/tutorial/tutorial.txt
  

Modding

Documentation

Effects • Triggers • Defines • Modifiers • List of modifiers • Scopes • Localisation • On actions • Data structures (Flags, Event targets, Country tag aliases, Variables, Arrays)