Triclon B Map Format

Introduction

Why binary?

I can already hear some of the '133t hackers moan, "why use binary formats which are hard to edit and offer little advantage over text-based formats. Sure, text is a bit verbose, but what if I want to edit my maps using Vi/Emacs/<insert_favourite_text_editor/>?"

It's quite unlikely that you'll ever need to edit map files by hand. Besides, you can edit binary files by hand, you have heard of hex-editor's right? There are a lot of situations when small size is an important factor:

• Sharing of maps in multiplayer games (Think transfers over 9600baud modems)
• Transfer of files on floppies (CD-ROM, what's that?)
• Harddrives are expensive (Well not really, but I'm a cheap bastard)

Additionally plain-text files are slower to parse, and require developers to write more code.

The Format

Overview

A Triclon map consists of a series of points which define the shape of the ground, a different terrain-type can be used between each point. Additionally objects like houses, trees etc. can be placed on the map, but only on ground level (i.e no flying trees are allowed).

In the beginning there was 0x324d4354

Some operating systems identify file-types by file-extensions, some use MIME-types, while other use even more exotic methods. There are probably as many ways to identify file-types as there are operating systems.

Triclon B solves this problem by using a magic number in the beginning of every data-file to make sure that the file is of the correct type.

The first 4 bytes of every map should be 0x334d4354 on x86 and other little-endian platforms and on PowerPC's and other big-endian machines it should be 0x54434d33. This number corresponds the string "TCM3" (Triclon Map 2) in standard ASCII.

In this case 3 is the version of the map-format used. Newer formats will have a higher number.

It wasn't me, it was that other guy!

It's always nice to know who to blame when something doesn't work. That's why every map includes the name of it's creator, and the name of the map itself. Immediately after the magic number is a byte, which contains the length of the map's name, i.e the next n bytes contains the map's name.

After the map's name is yet another byte, which contains the length of the map creator's name. The next n bytes contains the name of the map's creator.

Since the lengths of the strings are encoded in singe bytes, the maximum length of these strings are 255. ATM only ASCII is supported, although it is possible that UNICODE support will be included some day.

Terra cognita

Next up is a list of points where the terrain-type changes. Before that however, is a 4 byte word containing the size of the list (in bytes naturally).

Every item in the list consists of a 2-byte word containing the index of the ground-point where the terrain will change, and a 2-byte word containing the new terrain-type.

Finally we're getting somewhere

By now you must be getting sick of reading this (I'm famous for my incomprehensible explanations). Don't dispair, we're almost there.

After the list of terrain-changes comes the actual list of points defining the terrain. Each point consists of a 4-byte x coordinate and a 4-byte y-coordinate. The coordinates are relative to the lower-left corner of the screen, and increase when moving up or to the right.

After finishing this part, you have a fully working, albeit perhaps a bit boring map.

The Final Frontier

After the list of points defining the terrain you can optionally include a list of objects that should be placed in the terrain.

Again, before the actual list is a 4-byte word containing the size of the list (in bytes).

Each point consists of a 4-bye x-coordinate and a 4-byte word containing the object type. No y-coordinate is needed as it's calculated based on the terrain hight.

Summary

A quick summary for those who don't like overly verbose descriptions of file formats:

UTS,L

Although we will try to do our best, this documentation will probably not always be up-to-date. If you have some basic understanding of C++, the best documentation is the map editor's sourcecode.

The relevant sections can be found in Map::Save()/Map::Load() located in editor/Map.cpp.