A comphrensive description of the OTBM format

OTBM Format Structure
For lack of better documentation I have written the following guide after my experience parsing the .OTBM file structure. I have written a script using NodeJS that converts the OTBM format to the human-readable JSON.

https://github.com/Inconcessus/OTBM2JSON.git

Using JavaScript is high-level approach and easier to follow compared to the native C++ approach. Since JSON is more semantic than an opaque binary structure, this intermediary format can be used to write other applications. The output format of this script can be seen here:

Inconcessus/OTBM2JSON

This is not a complete description of the format but most important details should be included.

Hope it helps,
Forby


High Level Format Description
The format is started with an intial 4 byte identifier that is followed by map metadata (e.g. version, width, height). After that all actual data is added in a nodal tree structure (described below).

• MAGIC_IDENTIFIER (4 bytes) - must be either empty or "OTBM"
  
• OTBM_HEADER (16 bytes) - Contains map metadata
• Structural node tree

OTBM Header
The header is 16 bytes long and contains some of the map metadata:

• version (4 bytes)
• map width (2 bytes)
• map height (2 bytes)
• items major version (4 bytes)
• items minor version (4 bytes)

Node Structure
The OTBM format is built up from a structural tree of nodes where each node may have an unlimited number of child nodes. Parsing these nodes can be a little bit tricky, so have a look at the code shared by this post. These are the most important nodes in its hierarchy:

• OTBM_MAP_DATA
  • OTBM_WAYPOINTS
    • OTBM_WAYPOINT
  • OTBM_TOWNS
    • OTBM_TOWN
  • OTBM_TILE_AREA
    • OTBM_TILE and OTBM_HOUSETILE
      • OTBM_ITEM
        • ... (items may be nested indefinitely; e.g. backpacks)

For example: an item node must have a parent tile node that indicates what tile the item is placed. In turn, that tile must have a parent area node that indicates the area on the map. This format is useful for describing items inside items.

Nodes are started by the marker 0xFE and terminated by 0xFF. A character followed by 0xFD is escaped and interpreted as literal. A node that is nested within another node becomes a child of the larger node. For example:


Describes a parent node with a single nested child. Most commonly this structure is practical when describing items on a map. The OTBM format can describe an item inside a container on a specific tile on the map: Area -> Tile -> Item (bag) -> Item (coin). In nodal terms:


OTBM Node Descriptions

Following comes a description of the individual nodes. Each nodes have an intial byte that determines its type:

• OTBM_MAP_DATA = 0x02;
• OTBM_TILE_AREA = 0x04;
• OTBM_TILE = 0x05;
• OTBM_ITEM = 0x06;
• OTBM_TOWNS = 0x0C;
• OTBM_TOWN = 0x0D;
• OTBM_HOUSETILE = 0x0E;
• OTBM_WAYPOINTS = 0x0F;
• OTBM_WAYPOINT = 0x10;

Nodes may have some required attributes followed by some optional properties (refer to the section on reading additional node properties below).

OTBM_MAP_DATA (Serves as a parent for following nodes; has some string data describing RME -- we can ignore this).

• N Additional properties (e.g. description, house & spawn file names)

OTBM_TILE_AREA (5 bytes)
The tile area node has three properties starting after the initialization byte 0xFE:

• x - 2 bytes
• y - 2 bytes
• z - 1 byte

OTBM_TILE (N bytes)
The tile node has two required properties that indicate the position on the map. Note that this position is relative to the parent area node and only a single byte for each coordinate. To get the real position on the map add the parent area coordinates to the coordinates in this node. This type of position encoding saves roughly 50% in terms of storage space.

• x - 1 byte
• y - 1 byte
• N additional properties

OTBM_ITEM
Every item has an item identifier that is inherent to the item (e.g. 100 is void).

• id - 2 bytes
• N additional properties

OTBM_HOUSETILE
House tiles have three required properties:

• x - 2 bytes
• y - 2 bytes
• houseId - 4 bytes
• N additional properties

OTBM_TOWNS (serves as a parent for OTBM_TOWN)

OTBM_TOWN
House tiles have three required properties:

• id - 2 bytes
• name - N bytes (read TEXT similar to additional properties; but not prefixed by the magic 0x06)
  
• x - 2 bytes (temple position x)
  
• y - 2 bytes (temple position y)
  
• z - 1 byte (temple position z)

OTBM_WAYPOINTS (serves as a parent for OTBM_WAYPOINT)

OTBM_WAYPOINT
Waypoints have some required properties:

• name N bytes (read TEXT similar to additional properties; but not prefixed by the magic 0x06)
  
• x - 2 bytes
  
• y - 2 bytes
  
• z - 1 byte

Reading additional node properties

Most nodes have have an unlimited number of extra properties. These properties can be e.g. action id, unique id, text, count, or a teleport destination. These additional properties always follow after the required part of a node and are initiated by another magic byte number.

• 0x01 OTBM_ATTR_DESCRIPTION
• 0x02 OTBM_ATTR_EXT_FILE
  
• 0x03 OTBM_ATTR_TILE_FLAGS
  
• 0x04 OTBM_ATTR_ACTION_ID
• 0x05 OTBM_ATTR_UNIQUE_ID
• 0x06 OTBM_ATTR_TEXT
• 0x08 OTBM_ATTR_TELE_DEST
• 0x09 OTBM_ATTR_ITEM
• 0x0A OTBM_ATTR_DEPOT_ID
• 0x0B OTBM_ATTR_EXT_SPAWN_FILE
• 0x0D OTBM_ATTR_EXT_HOUSE_FILE
• 0x0E OTBM_ATTR_HOUSEDOORID
  
• 0x0F OTBM_ATTR_COUNT
• 0x16 RUNE OTBM_ATTR_RUNE_CHARGES

There are additional properties that have been omitted for the sake of brevity. Below is a detailed description of the above attributes:

TILE_FLAGS (4 bytes)
Following 0x03 are four bytes that acts as a bit mask for what zones apply to a given tile. We can use a bitwise AND of the magical four bits:

• TILESTATE_PROTECTIONZONE = 0x00000001
• TILESTATE_NOPVP = 0x00000004
• TILESTATE_NOLOGOUT = 0x00000008
• TILESTATE_PVPZONE = 0x00000010

ACTION_ID (2 bytes)
Following 0x04 there are two bytes that indicate the object action id.

UNIQUE_ID (2 bytes)
Following 0x05 there are two bytes that indicate the object unique id.

TEXT (N bytes)
Text may have a variable number of bytes depending on the length of the string. Following 0x06 we find a two byte number that indicates the length of the coming string. The string should be interpreted as ASCII.

e.g. 0x06 0x02 0x00 0x72 0x73 becomes the string: "HI"

TELEPORT_DESTINATION (4 bytes)
Following 0x08 we find five bytes that describe a position on the map:

• x - 2 bytes
• y - 2 bytes
• z - 1 byte

ITEM (2 bytes)
Following 0x09 we find two bytes that give the item identifier:

• id - 2 bytes

DEPOT_ID (2 bytes)
Following 0x0A we find a two byte number indicating the depot identifier. This attribute will only be found on depot items, obviously:

• id - 2 bytes

COUNT (1 byte)
Following 0x0F we find a single byte number indicating the item count:

• count - 1 byte

RUNE CHARGES (2 bytes)
Following 0x16 we find a two byte number indicating the number of charges on a rune:

• charges - 2 bytes

Example
The following hex representation of the format shows the OTBM for a single void tile (id: 100) in the top left corner (coordinates: 0, 0, 7). Emphasis on the fact that OTBM uses little endianness.

Code:

00 00 00 00
fe 00 02 00 00 00 00 08 00 08 03 00 00 00 39 00 00 00
    fe 02 01 22 00 53 61 76 65 64 20 77 69 74 68 20 52 65 6d 65 72 65 27 73 20 4d 61 70 20 45 64 69 74 6f 72 20 33 2e 33 01 1d 00 4e 6f 20 6d 61 70 20 64 65 73 63 72 69 70 74 69 6f 6e 20 61 76 61 69 6c 61 62 6c 65 2e 0b 0d 00 6d 61 70 2d 73 70 61 77 6e 2e 78 6d 6c 0d 0d 00 6d 61 70 2d 68 6f 75 73 65 2e 78 6d 6c
        fe 04 00 00 00 00 07
            fe 05 00 00 09 64 00 ff
        ff
        fe 0c ff
        fe 0f ff
    ff
ff

• OTBM Identifier (0x00000000)
• Map version (0x02000000 = 2)
• Map width (0x0008 = 2048)
• Map height (0x0008 = 2048)
• Major & Minor version (0x03000000, 0x39000000)
  
• Long root element (0x0201 .. 0x6d6c)
  
• Node starting with 0x04 (OTBM_TILE_AREA)
  • 04 00 00 00 00 07
    • x-coordinate (0x0000 = 0)
    • y-coordinate (0x0000 = 0)
    • z-coordinate (0x07 = 7)
• Node starting with 0x05 (OTBM_TILE)
  • 05 00 00 09 64 00
    • relative x-coordinate (0x00 = 0)
    • relative y-coordinate (0x00 = 0)
    • Identifier (0x6400 = 100)
• Waypoint & House nodes (closing tags)

Very usefull, thank you!

otbm format was designed only to hold informations of tibia maps?

beautiful reading, thanks a lot.

mattos123 said:

otbm format was designed only to hold informations of tibia maps?

Click to expand...

The nodal tree structure is commonly used because it saves a lot of resources. And in that sense it is generic.. but the rest is specific to OTBM.

want to know if it's possible to export uniqueid and actionsid and replace or simply add them from one map to another is it's does anybody know how to?