Map modding

From Crusader Kings II Wiki
Jump to navigation Jump to search

Many things can break the game while modding the map files, see troubleshooting.

The most important is the format used while saving, as wrong formats will cause CTDs while loading:

File Role Format
provinces.bmp Province boundaries RGB Color (24 bits), no color space information
world_normal_height.bmp Lighting
rivers.bmp Flow of minor rivers Indexed color (8 bits)
terrain.bmp Terrain textures
trees.bmp Tree types and density
topology.bmp Height of the terrain Greyscale (8 bits)

The height and width of these images should be multiples of 64 to avoid CTD at startup.

But in practice it needs to be a multiple of 256, otherwise some black bars will appear on the edge of the map.[1][edit | edit source] contains general information about the map. Most items in it should be left alone. Here are the ones you need to worry about:

  • max_provinces: This is the number of the last province + 1. If you forget to add one, the last province will get ignored.
  • sea_zones: This contains two sea province IDs that are at opposite ends of a range of contiguous sea province IDs. You must have exactly two province IDs listed for each sea zone. You may have multiple sea_zones defined, one for each range of contiguous sea provinces. Note: Each sea province in a sea zone is considered to be reachable by ship from every other one in the same sea zone. (Exception: A sea province that has no neighboring sea provinces is assumed by the game to be a lake, and does not generate ports adjacent to it.)
  • ocean_region: This contains a list of sea zones (automatically numbered based on their position in the file), all of which can be navigated to from the others. You may have multiple ocean_regions.
  • major_rivers: All sea zones listed here are major rivers, and can be navigated by any religion with allow_rivermovement = yes.
  • externals: A list of points that are considered outside all provinces. Used (for instance) as the start points of trade routes that extend off the map. A single point of the color defined for this province is placed on the map in the direction the trade route is intended to come from.

Note: sea_starts was made obsolete as of patch 2.1 (Rajas of India). The above information is current as of patch 2.6.

Provinces[edit | edit source]


Provinces.bmp is probably the most important file in your map, because it shows the boundaries of all counties and sea zones. Each color corresponds to an entry in definition.csv. When editing provinces.bmp, make sure to only use solid colors, and no antialiasing, transparency, or anything else.

The .bmp file's default size is 3072 x 2048 pixels.

Adding a province[edit | edit source]

Adding a province requires to follow many steps. Here is a list of what needs to be done.[2]

  • Choose a colour that's not already taken. In case of uncertainty of how to find a new one, pick one of the already existing RGB values at the end of map/definition.csv. You can use the RGB values of other Clausewitz games which have a higher province count (like HoI4 with >13k)
  • Colour in the province on map/provinces.bmp. Make sure to only use solid colours, and no antialiasing, transparency, or anything else. If GIMP is used, follow the instructions on GIMP editing.

If everything was done right, when the game is opened it should be possible to see the new province in grey on the map.

  • Create a file with the number and name of the province in history/provinces/
  • Create a history file for the title in history/titles/.
  • Add an entry for the province in the appropriate common/province_setup/ file. (Unless you are modding older versions, this is no longer needed)
  • Add the name of the province in the appropriate localisation/ file for province names.
  • Add the name of the title in the appropriate localisation/ file for titles.
  • Add a coat of arms for the title in gfx/flags/. It needs to be 128x128 and saved as .tga
  • Fix the positions of the new province using the Nudge tool

GIMP editing[edit | edit source]

When using the Pencil tool, set mode to Dissolve, brush "Hardness 100", size 1.00, and dynamics to "Dynamics Off". When using Bucket Fill, set mode to Dissolve.

When saving, make sure "Do not write color space information" under Compatibility Options is checked, and under Advanced Options pick 24 bits, R8 G8 B8. Using different settings will cause CTDs while loading.

Definition[edit | edit source]

The file definition.csv lists all provinces and their colors in provinces.bmp. Each line is formatted like this:


1 is the province's id number. 42,3,128 is its RGB color in provinces.bmp. Vestisland is the name of the province, but the name that actually shows up on the map is determined by the localisation. The "x" is just there to mark the end of the line.

Adjacencies[edit | edit source]

Adjacencies.csv is used to make special connections between provinces. This file can be associated with Microsoft Excel although it is advised to use text editors like Notepad++ when editing this file.

Seas[edit | edit source]

Connections through seas are often used to connect pieces of land that are close together, for example the Aegean islands.

Making a connection for two provinces through a sea is coded like this:

Province number 1;Province number 2;sea;The sea the connection will go through;X₁;Y₁;X₂;Y₂;Comment

For example is this the connection between Corsica and Sardinia:


In most cases, the game automatically chooses a point in each province based on proximity to draw the crossing path. If custom points are required (for example to prevent overlap with other crossings, to simulate a historical crossing point, or simply for stylistic reasons) the parameters X₁, Y₁, X₂ and Y₂ may be used to define these points. In most cases this isn't necessary, so these values are set to -1, allowing the game to determine the points automatically.

Major rivers[edit | edit source]

Connections through Major rivers are used to connect the land that would be connected if there were a normal river or no river at all.

Making a connection for two provinces through a major river is coded like this:

Province number 1;Province number 2;major_river;The major river that the connection will cross;-1;-1;-1;-1;Comment

For example, this is the connection between Holland and Breda across the Rhine:


Portages[edit | edit source]

A Portage is a connection for seas through land. Portages are coded like this:

Sea number 1;Sea number 2;portage;The land province the connection will go through;X₁;Y₁;X₂;Y₂;Comment

For example this is the connection for the Don and the Volga:


Like sea crossings, the X₁, Y₁, X₂ and Y₂ parameters may be used to define where the crossing is drawn.

Positions[edit | edit source]

Main article: Positions.txt

The file positions.txt determines where cities, ports, councillors and armies are placed on a province.

Rivers[edit | edit source]


Rivers.bmp shows all minor rivers on the map. It does not include major navigable rivers, which are treated as sea zones, and colored pink in rivers.bmp.

Any river that merges with or splits from another river is part of a river system. Each river system can only have one source (green dot). Each individual river can only be one pixel. Two river pixels must be orthogonally (not diagonally) adjacent to be part of the same river. When a river joins another river, a red dot needs to be used. In addition, the color of the river corresponds with the size of the river and the defense bonus received. [3]

rivers.bmp uses an indexed color palette. CTDs will occur if you save it without the right palette, so I recommend opening the vanilla rivers.bmp and copying and pasting your map over it.

Category Color RGB Hex Code
River Source 0 255 0 #00FF00
Minor River source from Major River 0 158 0 #009E00
Merging River 255 0 0 #FF0000
Splitting River 255 252 0 #FFFC00
Water & Major Rivers 255 0 128 #FF0080
Land 255 255 255 #FFFFFF
Rivers 0 255 255 #00FFFF
0 200 255 #00C8FF
0 150 255 #0096FF
0 100 255 #0064FF
0 0 225 #0000E1
0 0 200 #0000C8
0 0 150 #000096
0 0 100 #000064

Some other colors are in the index of rivers.bmp, but their usage is not clear. They do seem to work as rivers as long as there is river source.

Note Color RGB Hex Code
0 85 0 #005500
Not in the vanilla rivers.bmp 0 125 0 #007D00
24 206 0 #18CE00

Terrain[edit | edit source]


Terrain.bmp is the file that determines the texture of your map and terrain combat modifiers in a province (although the modifiers can be overridden manually in the files found in history/provinces). The file is a 4-bit indexed bitmap and so contains a total of 16 possible colors (indices); however, only 14 of these are used on the default map. Each index is mapped to a particular terrain type in map/terrain.txt.

Each of the indices corresponds to the tile index in the sprite map/terrain/ to use for rendering. Several of the indices map to the same terrain type and are merely used to change the texture used - from a gameplay perspective they are identical.

The two indices (13 and 14) which are not used by the base game may still be used by modders. By default they are mapped to the same terrain type as index 15 (i.e. water/ocean; referred to in terrain.txt as coastal_desert) but can be re-mapped in terrain.txt. By default both use a dark brown soil texture (found in the two bottom middle boxes of map/terrain/

Index Color Type Default terrain type mapped to in terrain.txt RGB Notes
0 Plains plains 86 124 27
1 Farmland farmlands 138 11 26
2 Coastal desert plains 130 158 75 Mix between desert and patches of grass.
3 Desert desert 206 169 99
4 Sandy mountain mountain 112 74 31 Should be in the valleys or where the desert meets the mountains
5 Steppe steppe 255 186 0
6 Arctic arctic 13 96 62 Similar color to pine needles
7 Desert mountain mountain 86 46 0 Mix of desert and mountain rock
8 Forest hills 0 86 6
9 Snowless mountain mountain 65 42 17
10 Snow covered mountain 155 155 155
11 More snow covered mountain 255 255 255
12 Jungle jungle 40 180 149
13 N/A coastal_desert 213 144 199 Not used in the base game
14 N/A 127 24 60
15 Water 69 91 186 On the default map this covers all sea/ocean areas and navigable rivers. Additionally it extends approximately 1 pixel in around coastlines, giving the appearance of a beach

Example of the mapping of Plains (index 0) and Coastal desert (index 2) to the same plains terrain in map/terrain.txt, allowing to use a different texture for each one:

categories =  {

  plains = {
	movement_cost = 1.1
	color = { 241 221 184 }
	supply_limit = 5
	bottleneck_chance = 5


text_0 = { type = plains color = { 0 } priority = 0 }
text_2 = { type = plains color = { 2 } priority = 2 }

Trees[edit | edit source]


The trees.bmp file determines where the trees are, how many there are, and what type of tree they are.

Each colored pixel corresponds to one in-game clump of trees. Note that tree.bmp in the base game is 8.04188481675 times smaller than the other .bmp files so divide the map dimensions by 8.04188481675 and use the result as a reference for this. Custom tree.bmp files may be different sizes/scales than this, but higher-resolution files may cause performance issues as more trees will be spawned on the map, and will lead to a higher density of tree groups, which may be visually unappealing.

Type[edit | edit source]

There are 4 types of trees:

Category Density 1 Density 2 Density 3 RGB Hex Code
Palm trees [{{{1}}}] 255 255 0 #FFFF00
Coniferous trees 30 139 109 #1E8B6D
Mediterranean trees 154 156 51 #9A9C33
Deciduous trees 76 156 51 #4C9C33

Density and size[edit | edit source]

Each pixel in trees.bmp represents a hexagon of trees in game.

The darker the color the more dense & larger the trees.

For instance if we use the lightest color of deciduous trees we will get a hexagon of 6 or more small trees. If we use the darkest color we get a hexagon of full of bigger trees.

Topology[edit | edit source]


Topology.bmp is the file that determines the height of the terrain.

The topology of the map is determined by how white a pixel is, the whiter the higher. When editing this it is important that you make the coast above the water so that it doesn't break the game.

Note that the highest value for water is 94/94/94 , while the lowest value for land is 96/96/96. Avoid using 95/95/95 which can cause buggy behaviour. Note: the file must be saved in grayscale format, which can't always be done in common graphics editors such as

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

Lighting[edit | edit source]


World_normal_height.bmp is a normal map which provides the game with information on how to light the map. As of version 3.2, the maximum size of a square world_normal_height.bmp is 3344×3344 (i.e. 2092×256 pixels or just over 11.18 megapixels). Normal maps of a different aspect ratio may exceed one of these dimensions as long as the total area does not. Exceeding this area will cause your terrain to have no lighting and therefore be very dark. Fortunately, world_normal_height.bmp does not have to be the same dimensions as your other map files, or even the same aspect ratio; smaller (or larger) normal maps will be scaled automatically to the map's dimensions.

Normal maps can be generated from the height map (topology.bmp) using Nvidia's texture tools, or by using Filter > 3D > Generate Normal Map in Photoshop CC.

Colormaps[edit | edit source]

Ck2 uses two colormaps, both of which can be found in the terrain sub-directory of the map directory, and . They add additional detail to the map, acting as an overlay for the land and water, respectively. Like world_normal_height.bmp they scale to the total dimensions of your map. Unlike other map files, they use the dds format, which may require a special plugin to load or edit.

When using the Nvidia dds plugin to save the colormaps, save them as "DXT5 ARGB 8 bpp | interpolated alpha" with 2D textures and no MIP maps

Climate[edit | edit source]

Modding the climates of provinces works somewhat similarly to geographic_region and island_region, except here only provinces work. This means that all provinces that have some sort of climate need to have their province ids added to the appropriate block.

Although it is tedious, it is very simple. For example, in a world with 16 provinces, here is an example of how to add climates:

mild_winter = {
    1 2 3 4
normal_winter = {
    5 6 7 8
severe_winter = {
    9 10 11 12

Provinces 13, 14, 15 and 16 will have temperate climate. This does not have to be added. Any provinces that have not been placed inside one of the blocks will automatically get temperate climate. If provinces are placed in multiple blocks, the lowest block it is placed in will be used (but it is still recommended to avoid placing provinces in multiple blocks).

Frame[edit | edit source]

The map frame is defined in the folder static. Predefined values are:

  • frame (2048x2048)
  • frame3072 (3072x2048)
  • frame3200 (3200x[{{{1}}}])
  • frame4096 (4096x[{{{1}}}])
  • Landmark_Domeoftherock ([{{{1}}}])

With an empty file, the map will have no frame. If your custom map is not in the same ratio it's possible to add a custom frame. You will need to do make a new one and export it in a pxdmesh format and change the 00_static.txt and mapitems.gfx

Fonts[edit | edit source]

See Custom Map Fonts.

Minimap[edit | edit source]

In addition to graphics files, creating a custom minimap also requires some interface modding. See here for more.

Troubleshooting[edit | edit source]

This section is dedicated to troubleshooting map issues. For other modding, see also generic troubleshooting.

Symptom Troubleshooting
Provinces do not show up on realm view
  • Check error.log for "Province xxx has no pixels in provinces.bmp" for all the provinces defined in definition.csv
  • Verify provinces.bmp is saved without color space information.

Tools[edit | edit source]

  • GIMP: A free image editing program, similar to Photoshop. Available for Windows, Mac, and Linux.
  • Map Filler: Fills in definitions.csv, landed titles, localisation, and province and title histories.
  • Clausewitz Map Checker: Validates provinces.bmp and definition.csv.
  • Nudge - A tool built into the game allowing map positions to be edited from within the game engine.

Links[edit | edit source]

References[edit | edit source]