Analysis of the binary Tibia map file format

File name format

Tibia client versions up to 10 store their map files in the Automap directory:

Each file within that folder contains the map data for a tile of 256×256 pixels. Each *.map file has a name of the form xxxyyyzz.map, where…

Example map file

I’ll be using 12612507.map as an example throughout this guide. This file contains the data for an area near Thais. To follow along, use your own map file, or quickly download a copy:

$ wget https://tibiamaps.github.io/tibia-map-data/Automap-with-markers/12612507.map

File structure

A *.map file consists of three main parts:

  1. The first 0x10000 (= 65536 = 256×256) bytes contain visual map data.
  2. The following 0x10000 bytes contain pathfinding data.
  3. The remaining bytes contain map marker data.

Visual map data

The first 0x10000 (256×256) bytes of the map file form the graphical portion of the map. Each byte represents a single visible map pixel. The map data first contains the 256 pixels in the first column, then the 256 pixels in the second column, etc. — the pixels go from top to bottom, rather than from left to right.

$ hexdump -v -C -n 65536 12612507.map
00000000 33 33 33 33 33 33 33 33 33 33 33 33 33 ba 33 33 |3333333333333.33|
00000010 33 33 33 33 18 18 18 18 0c 0c 18 18 18 18 18 18 |3333............|
00000020 18 18 18 18 ba ba ba ba ba ba ba ba ba ba ba ba |................|
00000030 0c ba ba ba ba ba ba 81 81 81 ba 18 18 18 18 18 |................|
00000040 ba 18 18 18 18 18 0c 18 18 18 18 18 18 18 18 18 |................|
00000050 0c 18 0c 18 18 18 18 18 18 18 18 18 18 18 18 33 |...............3|
00000060 33 33 33 18 18 18 18 18 18 33 33 33 18 18 18 18 |333......333....|
00000070 18 18 18 18 33 33 33 33 33 33 33 33 33 33 33 33 |....333333333333|
00000080 33 33 33 33 33 33 33 33 33 18 18 18 56 56 18 18 |333333333...VV..|
00000090 18 56 56 18 18 18 18 33 33 33 33 33 33 33 33 33 |.VV....333333333|
000000a0 33 33 33 33 33 33 33 33 33 33 33 33 33 33 33 33 |3333333333333333|
000000b0 33 33 33 33 33 33 33 33 33 33 33 33 33 33 33 33 |3333333333333333|
000000c0 33 33 33 33 33 33 33 33 33 33 33 33 33 33 33 33 |3333333333333333|
000000d0 33 33 33 33 33 33 33 33 33 33 33 33 33 33 33 33 |3333333333333333|
000000e0 33 33 33 33 33 33 33 18 18 ba 81 81 81 81 81 ba |3333333.........|
[…]
0000ff20 18 18 18 18 18 18 18 18 18 18 56 18 18 18 18 56 |..........V....V|
0000ff30 56 56 56 56 56 56 56 56 56 56 56 56 81 81 56 56 |VVVVVVVVVVVV..VV|
0000ff40 56 56 56 c0 c0 56 56 56 56 56 81 81 56 56 56 56 |VVV..VVVVV..VVVV|
0000ff50 56 56 56 56 56 56 18 18 18 18 18 18 81 81 18 18 |VVVVVV..........|
0000ff60 18 18 18 0c 0c 0c 18 18 18 0c 18 18 0c 0c 18 18 |................|
0000ff70 18 18 18 18 18 18 18 56 56 56 18 18 18 18 18 18 |.......VVV......|
0000ff80 18 18 0c 18 18 18 18 18 0c 0c 18 18 0c 0c 18 18 |................|
0000ff90 18 18 18 18 18 33 33 33 33 18 18 0c 18 0c 0c 0c |.....3333.......|
0000ffa0 0c 18 0c 18 18 18 18 18 33 33 33 33 33 33 33 33 |........33333333|
0000ffb0 33 18 0c 18 18 18 18 18 33 33 33 33 33 33 33 33 |3.......33333333|
0000ffc0 33 33 33 33 33 33 33 33 33 33 33 33 33 33 33 33 |3333333333333333|
0000ffd0 33 33 33 33 33 33 33 33 33 33 33 33 33 33 33 33 |3333333333333333|
0000ffe0 33 33 33 33 33 33 33 33 33 33 33 33 33 33 33 33 |3333333333333333|
0000fff0 56 81 81 0c 81 81 81 18 18 18 56 56 18 18 81 81 |V.........VV....|
00010000

The official Tibia servers only use a handful of color IDs:

Byte value / color ID Meaning Color
0x00 empty or unexplored area black
0x0C tree dark green
0x18 grass light green
0x33 water blue
0x56 rock/mountain dark gray
0x72 earth/stalagmite dark brown
0x79 earth brown
0x81 stone tile/cobbled pavement gray
0x8C light spot in grassy area light green
0xB3 ice light blue
0xBA wall red
0xC0 lava orange
0xCF sand beige
0xD2 ladder/stairs/hole/… yellow
0xD7 snow white

However, the Tibia client recognizes any byte value — even those that aren’t used on the official servers — and assigns a different color to each value. This means it’s possible to create fake map files that contain colors that aren’t used anywhere in the real game map.

Pathfinding data

The next 0x10000 bytes form the map that is used for pathfinding. Each of these 256×256 bytes represents the walking speed on a specific tile. In general, the lower the value, the higher your movement speed on that tile. There are two known constants:

$ hexdump -v -s 0x10000 -n 65536 -C 12612507.map
00010000 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff |................|
00010010 ff ff ff ff 96 96 96 96 ff ff 96 96 96 96 96 96 |................|
00010020 96 96 96 96 ff ff ff ff ff ff ff ff ff ff ff ff |................|
00010030 ff ff ff ff ff ff ff 6e 6e 6e ff 96 96 96 96 ff |.......nnn......|
00010040 ff 96 96 96 96 96 ff 96 96 96 96 96 96 96 96 96 |................|
00010050 ff 96 ff 96 96 96 96 96 96 96 96 78 78 78 96 ff |...........xxx..|
00010060 ff ff ff 96 96 96 96 96 96 ff ff ff 96 96 78 78 |..............xx|
00010070 78 96 96 96 ff ff ff ff ff ff ff ff ff ff ff ff |x...............|
00010080 ff ff ff ff ff ff ff ff ff 96 96 96 ff ff 78 ff |..............x.|
00010090 78 ff ff 78 96 96 96 ff ff ff ff ff ff ff ff ff |x..x............|
000100a0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff |................|
000100b0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff |................|
000100c0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff |................|
000100d0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff |................|
000100e0 ff ff ff ff ff ff ff 96 96 ff ff 64 64 64 ff ff |...........ddd..|
[…]
0001ff20 96 96 78 78 78 78 78 78 78 78 ff 96 96 96 96 ff |..xxxxxxxx......|
0001ff30 ff ff ff ff ff ff ff ff ff ff ff ff 96 96 ff ff |................|
0001ff40 ff ff ff ff ff ff ff ff ff ff 96 96 ff ff ff ff |................|
0001ff50 ff ff ff ff ff ff 96 96 96 96 96 96 6e 6e 96 96 |............nn..|
0001ff60 96 96 96 ff ff ff 96 96 96 ff 96 96 ff ff 96 96 |................|
0001ff70 96 96 96 96 96 96 96 ff ff ff 96 96 96 96 96 96 |................|
0001ff80 96 96 ff 96 96 96 96 96 ff ff 96 96 ff ff 96 96 |................|
0001ff90 96 96 96 96 96 ff ff ff ff 96 96 ff 96 ff ff ff |................|
0001ffa0 ff ff ff 96 96 96 96 96 ff ff ff ff ff ff ff ff |................|
0001ffb0 ff 96 ff 96 96 96 96 96 ff ff ff ff ff ff ff ff |................|
0001ffc0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff |................|
0001ffd0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff |................|
0001ffe0 ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff ff |................|
0001fff0 ff a0 a0 ff a0 a0 a0 96 96 96 ff ff 96 96 6e 6e |..............nn|
00020000

Map marker data

The remaining bytes contain the map marker data.

$ hexdump -s 0x20000 -n 65536 -C 12612507.map
00020000 07 00 00 00 0e 7e 00 00 ab 7d 00 00 02 00 00 00 |.....~...}......|
00020010 18 00 46 75 72 79 20 47 61 74 65 20 28 77 6f 72 |..Fury Gate (wor|
00020020 6c 64 20 63 68 61 6e 67 65 29 41 7e 00 00 d3 7d |ld change)A~...}|
00020030 00 00 09 00 00 00 07 00 48 61 72 62 6f 75 72 5b |........Harbour[|
00020040 7e 00 00 e2 7d 00 00 0a 00 00 00 0c 00 44 65 70 |~...}........Dep|
00020050 6f 74 20 26 20 62 61 6e 6b 5e 7e 00 00 ee 7d 00 |ot & bank^~...}.|
00020060 00 08 00 00 00 1b 00 4f 66 66 6c 69 6e 65 20 74 |.......Offline t|
00020070 72 61 69 6e 69 6e 67 20 28 64 69 73 74 61 6e 63 |raining (distanc|
00020080 65 29 61 7e 00 00 de 7d 00 00 0c 00 00 00 09 00 |e)a~...}........|
00020090 50 76 50 20 61 72 65 6e 61 71 7e 00 00 ef 7d 00 |PvP arenaq~...}.|
000200a0 00 05 00 00 00 06 00 54 65 6d 70 6c 65 8f 7e 00 |.......Temple.~.|
000200b0 00 dc 7d 00 00 03 00 00 00 0b 00 4d 61 67 69 63 |..}........Magic|
000200c0 20 73 74 6f 72 65 | store|
000200c6

The first 4 bytes indicate the number of markers on the map as a uint in little-endian byte order. If the file contains no markers, this byte sequence is 00 00 00 00 after which the file ends.

The structure of a single marker is as follows:

  1. The first byte is xOffset, i.e. the x position offset of the marker within this 256×256px tile, as a uint8.
  2. The second byte is xTile, i.e. the map tile the marker is in on the x axis, as a uint8. (This is the same value as the xxx component of the *.map file name.)
  3. The next two bytes are blank, i.e. 00 00.
  4. The next byte is yOffset, i.e. the y position offset of the marker within this 256×256px tile, as a uint8.
  5. The next byte is yTile, i.e. the map tile the marker is in on the y axis, as a uint8. (This is the same value as the yyy component of the *.map file name.)
  6. The next two bytes are blank, i.e. 00 00.
  7. The next 4 bytes represent the image ID of the marker icon, as a uint in little-endian byte order.
  8. The next 2 bytes indicate the size of the string that follows, as a uint in little-endian byte order.
  9. The next bytes represent the marker description as a windows-1252-encoded string. As a result, only the 128 symbols that can be represented in the windows-1252 encoding can be used in marker descriptions. Each marker description is limited to 99 such symbols — when viewed in the client, markers with descriptions exceeding 99 bytes are truncated, and the map file is updated with the truncated marker description.

This structure is repeated for every marker in the file, after which the file ends.

The following marker icon IDs are available:

Byte value / marker ID Short name Meaning
0x00 checkmark green checkmark ✔
0x01 ? blue question mark ❓
0x02 ! red exclamation mark ❗
0x03 star orange star 🟊
0x04 crossmark bright red crossmark ❌
0x05 cross dark red cross 🕇
0x06 mouth mouth with red lips 👄
0x07 spear spear 🏹
0x08 sword sword ⚔
0x09 flag blue flag ⚑
0x0A lock golden lock 🔒
0x0B bag brown bag 👛
0x0C skull skull 💀
0x0D $ green dollar sign 💰💲
0x0E red up red arrow up ⬆️🔺
0x0F red down red arrow down ⬇🔻
0x10 red right red arrow right ➡️
0x11 red left red arrow left ⬅️
0x12 up green arrow up ⬆
0x13 down green arrow down ⬇

Here’s what the marker icons look like in the Tibia client:

The Tibia client supports 20 different marker icons.

Converting between *.map files and images

The tibia-maps command-line utility can convert *.map files into separate files for each floor:

Compared to the binary *.map files, the PNG and JSON files are much easier for humans to view and compare, and better suited for version control. Here’s an example of a diff.

Of course, tibia-maps goes both ways — it can convert the PNG images and JSON data back into *.map files. This makes it possible to edit the map files without having to use the game client. If you just want to tweak some marker descriptions, for example, you could just modify the appropriate JSON file, and then use tibia-maps to turn everything back into an Automap folder the Tibia client can understand.