Original Post by Forbi on OtLand
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:
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:
0xFE <node>
0xFE <node> 0xFF
0xFF
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:
0xFE <OTBM_TILE_AREA>
0xFE <OTBM_TILE>
0xFE <OTBM_ITEM>
0xFE <OTBM_ITEM> 0xFF
0xFF
0xFF
0xFF
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.
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)