Map modding

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

The game map is defined by several layers of bitmaps and several text files that describe its features. All the relevant files are locates under /Hearts of Iron IV/map/.


Due to not preserving the order of colours in the index, or Microsoft Paint will not work for terrain.bmp or any .bmp files other than provinces.bmp and heightmap.bmp. GIMP or Photoshop is recommended.

In case GIMP is used, in the export settings while exporting to BMP on each map, you need to check the 'Disable writing colorspace information' box.[edit]

The file references the bitmaps and text files that make up the map. A basic version looks like this:

definitions = "definition.csv"
provinces = "provinces.bmp"
positions = "positions.txt"
terrain = "terrain.bmp"
rivers = "rivers.bmp"
heightmap = "heightmap.bmp"
tree_definition = "trees.bmp"
continent = "continent.txt"
adjacency_rules = "adjacency_rules.txt"
adjacencies = "adjacencies.csv"
#climate = "climate.txt"
ambient_object = "ambient_object.txt"
seasons = "seasons.txt"

# Define which indices in trees.bmp palette which should count as trees for automatic terrain assignment
tree = { 3 4 7 10 }

All file paths can be changed and are relative to the map/ directory. The following sections assume the standard file paths. The name itself is hard-coded.

The map's width and height are taken from provinces.bmp. They both have to be multiples of 256. The following files all need to have that same resolution:

  • heightmap.bmp
  • provinces.bmp
  • rivers.bmp
  • terrain.bmp

Province map[edit]

definition.csv contains the provinces the game recognizes and is arranged in the following format:

province id; r value; g value; b value; province type (land/sea/lake); coastal (true/false); terrain (plains/hills/urban/etc); continent (int)

The province ID, as well as the RGB value, must be unique. The valid terrain types are defined in /Hearts of Iron IV/common/terrain. The continent is a 1-based index into the continent list. Examples:

7;212;179;179;sea;true;ocean;1 - a coastal sea province
114;40;15;15;land;false;plains;1 - an inland plains province
260;170;235;235;land;true;urban;1 - a coastal urban province

If the province definitions are incomplete, the game creates a copy of this file in the user directory, with any incomplete or missing province definitions filled in. It might be necessary to delete this copy after making changes to the original file.[1]

HOI4 has a limit(between 19K and 22K) of displaying provinces. Last province before they don't get displayed anymore seems to be 21651 as of current knowledge. Apparently the representation of provinces also gets influenced if there are provinces which are split apart over larger distances

The file must have Windows-style line endings (CRLF!)

provinces.bmp controls the location and shape of the provinces on the map. Each pixel belongs to the province with the matching RGB value. Provinces that share a pixel edge neighbor each other and are connected. When debug mode is enabled, it will warn about the following conditions:

  • "Map invalid X crossing. Please fix pixels at coords": Four provinces share a common corner. The game connects the bottom left and the top right provinces but this situation is confusing to the player and should be avoided.
  • "Province X has TOO LARGE BOX. Perhaps pixels are spread around the world in provinces.bmp": The province has a width/height of more than 1/8th of the total map width/height. This might be an indication that two provinces inadvertently share a color.
  • "Province X has only N pixels": The province consists of no more than NGraphics.MINIMUM_PROVINCE_SIZE_IN_PIXELS (8 by default). This is likely too small to be easily usable by the player.

Provinces should be kept contiguous as much as possible. Large gaps will cause the game to crash.

The provinces.bmp file should be in RGB mode and saved as a 24-bit bitmap image file (.BMP). If the map is saved with a 32-bit format, the game will crash with a 'warning X4008: floating point division by zero' error.

Terrain map[edit]

terrain.bmp is an 8-bit indexed mode BMP file that controls the terrain assignment and textures. The indexes refer to the terrains at the bottom of /Hearts of Iron IV/common/terrain/00_terrain.txt. The terrain only affects the visuals of the map and paths between provinces; the provinces themselves use the assigned terrains from definitions.csv.

Tree map[edit]

trees.bmp controls the tree placement on the map. The resolution of the trees.bmp file affects the density of trees placed.

The trees.bmp file should be in Indexed mode and saved as a 8-bit bitmap image file (.BMP).

River map[edit]

River Map Colour Scheme.png

rivers.bmp controls the river placement on the map. Rivers must always be 1 pixel thick.

The rivers.bmp file should be in Indexed mode and saved as a 8-bit bitmap image file (.BMP).

colors used in rivers.bmp
Index Color Function
0 (0, 255, 0) The source of a river
1 (255, 0, 0) Flow-in source. Used to join multiple 'source' paths into one river.
2 (255, 252, 0) Flow-out source. Used to branch outwards from one river.
3 (0, 225, 255) River with narrowest texture.
4 (0, 200, 255) River with narrow texture
5 (0, 150, 255)
6 (0, 100, 255) River with wide texture.
7 (0, 0, 255)
8 (0, 0, 225)
9 (0, 0, 200)
10 (0, 0, 150)
11 (0, 0, 100) River with widest texture.

Indexes 0[2] up to including 6[3] are treated as small rivers for game mechanics, indexes up to including 11[4] as large rivers. To correctly render, each river must have exactly one marker, either a start marker (green/yellow) or an end marker (red).

If the path between two provinces overlaps at least one river pixel, it is considered a river crossing. If it intersects multiple river pixels of different types, the crossing type is implementation defined. To avoid player confusion, province paths should either clearly cut or stay clear of a river.

Height map[edit]

heightmap.bmp determines the 3D mesh of the map. ( 0, 0, 0 ) is the lowest point, with (255, 255, 255) being the highest. The sea level is set at (95, 95, 95), so any values below that will be submerged.

Make the transitions between heights smooth, otherwise you will create noticeable jagged edges.

The heightmap.bmp file should be in Greyscale mode and saved as a 8-bit bitmap image file (.BMP).

Normal map[edit]

world_normal.bmp determines the 3D bump map. This is required to correctly add shadow to the height map.

Normal maps can be created with Nvidia's texture tools from the heightmap.bmp, or by using Filter > 3D > Generate Normal Map in Photoshop CC. If you are using GIMP, download the Normal Map Plugin. Load the heightmap, change the image type to RGB and add the bump map filter by using Filter > Map > Normal. Remember to inverse the Y axis.

Color maps[edit]

The files define the overall color tint applied to the map. Without a colormap file, all land will appear the same overall color, regardless of terrain type.

They should be in RGB mode and saved in the .DDS format, using the ARGB 32 bpp profile with no mipmaps.

Water map[edit] controls the color tint applied to water.

The files should be in RGB mode and saved in the .DDS format, using the ARGB 32 bpp profile with no mipmaps.


The adjacencies file is found at /Hearts of Iron IV/map/adjacencies.csv. As a comma-separated file, you may open it with Excel or other similar programs, or a text editor. The default encoding is ANSI.

The file modifies and adds custom adjacencies between provinces on top of the normal connections defined by the provinces and rivers maps. For example it controls which provinces non-contiguously connect to other provinces. An island is normally not connected to any other land provinces, as there are sea provinces in the way. The adjacencies file tells the game to connect such provinces, allowing land units to walk between them. It also allows changing the properties of an existing connection, e.g. making them impassable, changing their type, or defining which provinces are gated by straits.

The format is as follows:

<province id>;<province id>;<type>;<province id>;<map coordinate>;<map coordinate>;<map coordinate>;<map coordinate>;<comment>

The type may be empty for a normal land connection, or "river"/"large_river"/"sea"/"impassable" for a connection of the respective type. The "through" field defines a province that can block the adjacency. While an enemy unit controls this province, the connection will be unavailable. -1 disables this feature; however, any adjacency with the type "sea" must have a province defined here. The map coordinates are used to adjust the starting and ending point of the graphic displaying the adjacency. If no adjustment is needed, use -1 in place of an actual coordinate. Optionally an adjacency rule can be referenced that controls access through the adjacency.

Even when otherwise empty, the file must be terminated with a line containing a negative from-field and a semicolon to prevent an infinite hang on start-up.

Strategic Regions[edit]

Every province must belong to a strategic region. If you interact with a province in-game and it does not belong to a state, you will experience a crash to desktop.

A strategic region may contain provinces from multiple states, but a state should not have provinces in multiple strategic regions as this can cause instabilities and will show a warning in error.log.

Strategic Regions are formatted as follows, in example:

		 2775 2799 2824 2847 2871 2895 2977 3528 4370 5929 7242 8450 8621 11748 12389 13004 13006 13007 

The color of the strategic region is random. However, you can manually define an area's color:

    color = { <r>, <g>, <b> }

The color definition used the default RGB values, which range from 0 to 255 (i.e. not decimal RGB).

Supply areas[edit]

All states must be associated with a supply area. Each supply area can take any number of states, and each state should be in only one supply area.

Supply areas are formatted as follows:

		5 85 


Found in continent.txt, located in the map folder, continents are used to group large swathes of provinces together as a traditional continent. Continents are used to define AI areas.

All land provinces must belong to a continent, otherwise you may experience errors/crashes.

The continents in the base game are (the number after the continent name is the ID):

Europe (2)

North America (3)

South America (4)

Africa (5)

Asia (6)

Middle East (7)

Pacific (8) (note that the pacific tag is only used for a few states near Australia, all the other pacific states are under the Asia tag)

Australia/Oceania (9)

Ambient Objects[edit]

The ambient_object.txt is used to define the cosmetic 3D objects found in the map. This includes the map frame, so don't simply empty the file if you want to remove the other objects.

The format for an ambient object is as follows:

# Used once for each graphical asset
type = {
    type = <string>         # Refers to the graphical asset in ambient_object.gfx
    use_animation= <yes/no> # Used set set if an object is animated or not
    scale = <float>         # Sets the scale of the asset. 1.0 is default size.
    time_duration=300.000   # Always set to 300 for animated objects, may be redundant
    always_visible = <yes>              # Used to force visibility
    visible_in_all_map_modes = <yes>    # Used to show is non-terrain mapmodes
    # Each instances is a separate object
    object = {
        name = <string>                 # Name does not have to be unique
        hidden_on_start = <yes/no>      # Whether the object is hidden (can be revealed with show_ambient_object)
        position = {
            <x>     # Horizontal coordinate
            <z>     # Height coordinate - 0.0 is base
            <y>     # Vertical coordinate
        rotation = {
            <x>     # Horizontal rotation
            <z>     # Height rotation - this is used for most rotations
            <y>     # Vertical rotation

You can use the Nudge tool to place new instances and move objects, but if you want to add a new type, you must add it to the file first, then use the Nudge tool.

The ambient objects for the canals are found here. To link them to the canal definition in, you need to make sure they share the same name (i.e. panama_canal).

Terrain Atlas[edit]

The terrain textures used for specific terrains are found in and

The association between the texture and terrain is found in /Hearts of Iron IV/common/terrain/00_terrain.txt. Within this file is the terrain scope which defines the terrain objects used by the game to interpret the terrain.bmp.

  • type is the terrain category assigned to provinces that are covered by the specified terrain in the terrain.bmp.
  • color is the indexed color from the terrain.bmp that represents this terrain object.
  • texture is the tile from the terrain atlas textures that this terrain object uses.

When the game automatically generates terrain (i.e. using the Nudger) these terrain objects are what control the assignment of terrain categories to provinces.

The and must be saved in DXT5 with Mipmaps enabled.

It is possible to increase the size of the texture atlas. In constants.fxh in /Hearts of Iron IV/gfx/FX/, edit the MAP_NUM_TILES variable to match your new number of columns and rows (a setting of 5.0 will result in 5 x 5 = 25 texture indices, as opposed to the vanilla 4 x 4).

It is possible to increase the size of the texture tiles within the texture atlas. In pdxmap.shader in /Hearts of Iron IV/gfx/FX/, edit the TEXELS_PER_TILE variable to your new size.


The seasons.txt file is used to define the color adjustments during the four seasons that pass in game. There are four seasons: winter, spring, summer and autumn.

The format for each is as follows:

<season> = {
    start_date = <date>      # 00.<month>.<day>, in numeric form, i.e. 00.12.01
    end_date = <date>
    # Applies to the northern hemisphere
    hsv_north = { <hsv> }    
    colorbalance_north = { <hsv> }
    # Applies to the equator
    hsv_center = { <hsv> }    
    colorbalance_center = { <hsv> }
    # Applies to the southern hemisphere
    hsv_south = { <hsv> }    
    colorbalance_south = { <hsv> }

The color format used is decimal HSV (Hue, Saturation, Value).

The seasons.txt file also controls the tree models visual appearance over the year.

Color map and city lights[edit]

/Hearts of Iron IV/map/terrain/ serves two purposes. The RGB channels define the default coloring of the map, which gets modified by terrain. When making changes to the terrain or height map, this color map should be updated too to reflect the changes visually. The alpha channel is used for city lights at night. More opacity means stronger lights.

The file should have half the vertical and horizontal resolution of the map.


It is possible to change the size of the map, with the majority of bitmap files requiring the same resolution.

  • The vertical and horizontal resolution should be a multiple of 256
  • world_normal.bmp should have half the vertical and horizontal resolution of the map
  • trees.bmp should have the vertical and horizontal resolution of the map at a ratio of 0.29296875
  • The maximum area of pixels does not exceed 13,107,200

It will be necessary to use the Nudge tool to adjust any ambient objects to suit the new map.

  1. forum:1153223