Analysis of the Tibia export file format used by the Flash client

Support TibiaMaps.io by bidding on a character auction!

To create an export file based on your current *.map files, open the Windows Tibia client, click “Options”, then “Export”, then “Yes”. By default, this file is saved as %APPDATA%\Tibia\Tibia.exp.

Export files use NDJSON with CRLF line endings (i.e. 0x0D 0x0A) and include a CRLF at the end of the file. Each line contains the map data for a tile of 256×256 pixels, and has the following format:

{"colordata":"…","mapmarkers":[{"description":"Fury Gate (world change)","type":2,"x":32270,"y":32171,"z":7}],"waypoints":"…","x":32256,"y":32000,"z":7}

This is minified JSON-formatted data. Here’s a slightly more readable version:

{
	"colordata": "base64(transpose(binaryMapData))",
	"mapmarkers": [
		{
			"description": "Fury Gate (world change)",
			"type": 2,
			"x": 32270,
			"y": 32171,
			"z": 7
		}
	],
	"waypoints": "base64(transpose(binaryPathfindingData))",
	"x": 32256,
	"y": 32000,
	"z": 7
}

Let’s go over these properties one by one.

Visual map data: colordata

The colordata property is a Base64-encoded string representing the binary visual map data. In export files, the pixel data goes from left to right. This differs from the format used in *.map files, where pixel data goes from top to bottom. To convert between these two formats, treat the binary buffer as a 256×256 matrix and transpose it.

Here’s a simplified example — assume these 9 bytes form the visual map data section as seen in a *.map file:

00 33 00 00 00 00 BA 00 00

This data can be represented as a 3×3 matrix:

00 33 00
00 00 00
BA 00 00

Transposed, this becomes:

00 00 BA
33 00 00
00 00 00

Or, in re-formatted form:

00 00 BA 33 00 00 00 00 00

After Base64-encoding this result, it’s ready to be used as a colordata value in an export file.

Map marker data: mapmarkers

The value for the mapmarkers property is an array. If there are no markers for this tile, it’s an empty array (i.e. []).

Each marker is represented by an object of the following format:

{
	"description": "Fury Gate (world change)",
	"type": 2,
	"x": 32270,
	"y": 32171,
	"z": 7
}

The description is a windows-1252-encoded string.

The type indicates the image ID of the marker icon. See our analysis of the binary Tibia map file format for an overview of the available icons.

Marker coordinates

The marker’s x and y values are different from those in the binary map file format. Markers in *.map files declare the xxx and yyy ID of the 256×256px tile they belong to, plus the x and y offsets within that tile. Export files use just a single, absolute value.

For example, a *.map file could contain a marker with the following properties:

• xTile is 124
• xOffset is 194
• yTile is 121
• yOffset is 66

To convert this to the absolute values used in *.exp files (and our online map viewer), use the following formulae:

x = xTile * 256 + xOffset
y = yTile * 256 + yOffset

This gives:

x = 124 * 256 + 194 = 31938
y = 121 * 256 +  66 = 31042

To convert the absolute x and y values found in export files back to the two values used in the *.map format:

xTile = Math.floor(x / 256)
xOffset = x % 256
yTile = Math.floor(y / 256)
yOffset = y % 256

Pathfinding data: waypoints

The value for the waypoints property is a Base64-encoded string representing the pathfinding data. Just like with the visual map data, it runs from left to right in export files, but from top to bottom in *.map files. To convert between these two formats, treat the binary buffer as a 256×256 matrix and transpose it.

Tile coordinates: x, y, and z

The tile ID represented by a *.map file is revealed by its xxxyyyzz.map file name. Export files consist of a single file only, so the tile IDs are encoded in each line through the x, y, and z properties.

For example, the file 12412108.map has x = 124 and y = 121. To convert these tile IDs to the coordinates used in *.exp files, just multiply each number by 256. This gives x = 31744 and y = 30976. The z coordinate value remains unchanged.

Converting map data to the *.exp format

The tibia-maps command-line utility can create *.exp files based on map data.

To programmatically convert *.map files into an export file, convert the maps to PNG images + JSON first, then re-read the previous sentence.