Map modding

From Crusader Kings II Wiki
Jump to: navigation, 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
word_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)[edit] 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.
  • 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.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.

Adding a province[edit]

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

  • Choose a colour that's not already taken. In case of uncertainty of how to find a new one, pick one the already existing RGB values at the end of map/definition.csv.
  • 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.
  • 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]

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.


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


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]

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:



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 is this 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.


Main article: Positions.txt

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



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.

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



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.


There are 4 types of trees:

Category Density 1 Density 2 Density 3 RGB Hex Code
Palm trees [Verification needed] 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]

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



Word_normal_height.bmp provides the game with information on how to light the map.


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


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

  • frame (2048x2048)
  • frame3072 (3072x2048)
  • frame3200 (3200x[Verification needed])
  • frame4096 (4096x[Verification needed])
  • Landmark_Domeoftherock ([Verification needed])

With an empty file, the map will have no frame.


See Custom Map Fonts.


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


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


  1. Guide on adding new provinces on the citadel forum