Documentation of the .otbm file structure

[zyzof]

I would like to better understand the structure of generated OTBM files. I haven't been able to find any solid documentation for this anywhere, so I am proposing we add something to the README or wiki pages.

[hampusborgos]

I wrote a very comprenhensive documentation on the old OTFans wiki, however that seems to be gone now. :/

[zyzof]

That was a pretty consistent theme when I tried to find any further information.

I've taken some rough notes after walking through IOMapOTBM::loadMap; I'll tidy it up over the next couple of days, and post here for review.

[zyzof]

Here we go. Let me know if you see anything blatantly missing or out of place.

Current tree structure:

OTBM_ROOTV1
|
|--- OTBM_MAP_DATA
|   |
|   |--- OTBM_TILE_AREA
|   |   |--- OTBM_TILE
|   |   |--- OTBM_HOUSETILE
|   |   |--- OTBM_ITEM
|   |
|   |--- OTBM_TOWNS
|       |--- OTBM_TOWN
|   |
|   |--- OTBM_WAYPOINTS
|   |   |--- OTBM_WAYPOINT

To describe the data within each node type, we have the following data structs:

struct OTBM_root_header
{
    uint32_t version;
    uint16_t width;
    uint16_t height;
    uint32_t majorVersionItems;
    uint32_t minorVersionItems;
};

struct OTBM_map_header_node {
    uint8_t node_id;        //= OTBM_MAP_DATA;
    uint8[] attributes;     //OTBM_ATTR_DESCRIPTION || OTBM_ATTR_EXT_SPAWN_FILE || OTBM_ATTR_EXT_HOUSE_FILE
    uint8 null_byte;        // = 0;
};

struct OTBM_tile_area {
    uint8_t node_id;        //= OTBM_TILE_AREA
    uint16_t base_x;
    uint16_t base_y;
    uint8_t base_z;
};

struct OTBM_tile {
    uint8_t x_offset;
    uint8_t y_offset;
    uint8_t[] attributes; // OTBM_ATTR_TILE_FLAGS || OTBM_ATTR_ITEM.
    uint8_t null_byte;   // = 0;
};

struct OTBM_housetile {
    uint8_t x_offset;
    uint8_t y_offset;
    uint32_t house_id;
    uint8_t[] attributes;// OTBM_ATTR_TILE_FLAGS || OTBM_ATTR_ITEM.
    uint8_t null_byte;
};

struct OTBM_item {
    uint8_t node_type; // = OTBM_ITEM;
    //Item::Create_OTBM does more with remainder of data. Still need to go over this.
};

struct OTBM_towns {
    uint8_t node_type; //= OTBM_TOWNS;
};

struct OTBM_town {
    uint8_t node_type; //= OTBM_TOWN
    uint32_t town_id;
    std::string town_name;
    uint16_t temple_x;
    uint16_t temple_y;
    uint8_t temple_z;
};

struct OTBM_waypoints {
    uint8_t node_type; //= OTBM_WAYPOINTS;
};

struct OTBM_waypoint {
    uint8_t node_type;  //= OTBM_WAYPOINT
    std::string waypoint_name;
    uint16_t x;
    uint16_t y;
    uint8_t z;
};

If wanted, I could submit a PR making use of structs like this, in the interests of more self-documenting code. I'd also like to update the tree structure comment currently in iomap_otbm.cpp to better reflect the current system.

[hampusborgos]

OTBM_Item has a list of attributes following the item ID. In earlier version, charge/count was written as a byte directly after the item ID. However, since CIP started changing which items had charges, and which did not this system broke down. So now charges in a attribute as well. (You can see how the different attributes are read in Item.cpp and subclasses IIRC). ( see here: https://github.com/hjnilsson/rme/blob/master/source/iomap_otbm.cpp#L79 )

The attributes on OTBM_tile work the same way. Here we also have a special attribute for the "Ground" item, this is a special space-saving thing, so we don't need to write a subtree for the node if there is only a single ground item on that tile (which is very commonly the case). This reduces file size by 50% or so. ( see here: https://github.com/hjnilsson/rme/blob/master/source/iomap_otbm.cpp#L791 )

OTBM_tile_area in SimOne's map editor contains ALL tiles in a 256x256 slice of the map. However, my map editor has no easy way to iterate the tiles in this order due to the data structure, so it will write several different tile_area nodes concerning the same area in the file.

If you got any questions I can help you out.

[Inconcessus]

For who is looking: I wrote some more documentation on the .otbm format here: https://otland.net/threads/a-comphrensive-description-of-the-otbm-format.258583/. Might translate it to markdown and put it on GitHub too.