Modding

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.

Guidelines[edit]

  • 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++, Sublime Text, or Visual Studio Code) 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. The launch options are accessed in the menu opened by right-clicking the game and choosing 'Properties..'.

Advantages to using debug[edit]

  • 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. Note that, however, this only applies to files that were edited mid-session, not created.
  • 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.
  • 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. 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.
  • 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, and et cetera.
  • Access to more console commands - Certain console commands are locked for developers only and debug mode allows the player to use them.

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

Mod Structure[edit]

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]

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

name = "Minor Mod"
path = "mod/MinorMod"
picture = "thumbnail.png"
version = "v1"
supported_version = "1.10.*"
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.
  • 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 the mod completely overwrite a game's folder. As such, if you replace the path to history/states, there will not be any states other than the ones that you put in the mod's history/states. This has no effect on gfx folders. Exceptions to that are where the game does not directly pick the path for the image, which are gfx/loadingscreens, gfx/fonts, gfx/entities, and et cetera. This does not include gfx/flags, as the names in that folder have to be precise, meaning the game directly routes to that folder in the code.
  • dependencies makes the mod load over another one. This will ensure that the mod will overwrite the specified mod's contents, and it's necessary for sub-mods. Despite its name, the mod which is marked as a dependency is not necessary to be turned on to open this mod. This is necessary for sub-mods to work correctly

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.

Checksum[edit]

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]

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[edit]

Useful knowledge[edit]

In order to find something in multiple files, 'search in files' can be used inside a text editor. Visual Studio Code, Sublime Text, and Notepad++ have Ctrl+Shift+F as the hotkey for that function, and it's not present in Microsoft Notepad. This can be used to find where exact localisation is located or where an event is triggered in a matter of half of a minute.

In order to find the location of most sprites, the 'gui' console command can be used. That will give the name of the sprite when hovering over it, beginning with GFX_. A search inside of all files in the /Hearts of Iron IV/interface/ folder using the method above will find the definition of the sprite inside of a *.gfx file. It can also be enabled in the main menu by using the ` button.

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 Modding Coop, the Modding Plaza, and the 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.

See also[edit]

References[edit]