Home

TMX Documentation

TMX parses the map and loads everything into a public datastructure, then it's up to you to browse the datastructure.

Datastructure

See the TMX map format reference page.

View fullres.

enum tmx_map_orient {O_NONE, O_ORT, O_ISO, O_STA, O_HEX};
enum tmx_map_renderorder {R_NONE, R_RIGHTDOWN, R_RIGHTUP, R_LEFTDOWN, R_LEFTUP};
enum tmx_stagger_index {SI_NONE, SI_EVEN, SI_ODD};
enum tmx_stagger_axis {SA_NONE, SA_X, SA_Y};
enum tmx_layer_type {L_NONE, L_LAYER, L_OBJGR, L_IMAGE};
enum tmx_objgr_draworder {G_NONE, G_INDEX, G_TOPDOWN};
enum tmx_shape {S_NONE, S_SQUARE, S_POLYGON, S_POLYLINE, S_ELLIPSE, S_TILE};

/* typedefs of the structures below */
typedef struct _tmx_prop tmx_property;
typedef struct _tmx_img tmx_image;
typedef struct _tmx_frame tmx_anim_frame;
typedef struct _tmx_tile tmx_tile;
typedef struct _tmx_ts tmx_tileset;
typedef struct _tmx_obj tmx_object;
typedef struct _tmx_objgr tmx_object_group;
typedef struct _tmx_layer tmx_layer;
typedef struct _tmx_map tmx_map;

typedef union {
	int integer;
	float decimal;
	void *pointer;
} tmx_user_data;

struct _tmx_prop { /* <properties> and <property> */
	char *name;
	char *value;
	tmx_property *next;
};

struct _tmx_img { /* <image> */
	char *source;
	unsigned int trans; /* bytes : RGB */
	int uses_trans;
	unsigned long width, height;
	/*char *format; Not currently implemented in QtTiled
	char *data;*/
	void *resource_image;
};

struct _tmx_frame { /* <frame> */
	unsigned int tile_id;
	unsigned int duration;
};

struct _tmx_tile { /* <tile> */
	unsigned int id;
	tmx_tileset *tileset;
	unsigned int ul_x, ul_y; /* upper-left coordinate of this tile */

	tmx_image *image;
	tmx_object *collision;

	unsigned int animation_len;
	tmx_anim_frame *animation;

	tmx_property *properties;

	tmx_user_data user_data;
};

struct _tmx_ts { /* <tileset> and <tileoffset> */
	unsigned int firstgid;
	char *name;

	unsigned int tile_width, tile_height;
	unsigned int spacing, margin;
	int x_offset, y_offset; /* tileoffset */

	unsigned int tilecount;
	tmx_image *image;

	tmx_user_data user_data;
	tmx_property *properties;
	tmx_tile *tiles;
	tmx_tileset *next;
};

struct _tmx_obj { /* <object> */
	unsigned int id;
	enum tmx_shape shape;

	double x, y;
	double width, height;

	int gid;

	double **points; /* point[i][x,y]; x=0 y=1 */
	int points_len;

	int visible; /* 0 == false */
	double rotation;

	char *name, *type;
	tmx_property *properties;
	tmx_object *next;
};

struct _tmx_objgr { /* <objectgroup> */
	unsigned int color; /* bytes : RGB */
	enum tmx_objgr_draworder draworder;
	tmx_object *head;
};

struct _tmx_layer { /* <layer> or <imagelayer> or <objectgroup> */
	char *name;
	double opacity;
	int visible; /* 0 == false */
	int offsetx, offsety;

	enum tmx_layer_type type;
	union layer_content {
		int32_t *gids;
		tmx_object_group *objgr;
		tmx_image *image;
	} content;

	tmx_user_data user_data;
	tmx_property *properties;
	tmx_layer *next;
};

struct _tmx_map { /* <map> (Head of the data structure) */
	enum tmx_map_orient orient;

	unsigned int width, height;
	unsigned int tile_width, tile_height;

	enum tmx_stagger_index stagger_index;
	enum tmx_stagger_axis stagger_axis;
	int hexsidelength;

	unsigned int backgroundcolor; /* bytes : RGB */
	enum tmx_map_renderorder renderorder;

	tmx_property *properties;
	tmx_tileset *ts_head;
	tmx_layer *ly_head;

	unsigned int tilecount; /* length of map->tiles */
	tmx_tile **tiles; /* GID indexed tile array (array of pointers to tmx_tile) */

	tmx_user_data user_data;
};

Functions

/* Load a map and return the head of the data structure
   returns NULL if an error occured and set tmx_errno */
tmx_map *tmx_load(const char *path);

/* Free the map data structure */
void tmx_map_free(tmx_map *map);

/* returns the tile associated with this gid, returns NULL if it fails */
tmx_tile* tmx_get_tile(tmx_map *map, unsigned int gid);

/* print the error message prefixed with the parameter */
void tmx_perror(const char*);

/* return the error message for the current value of `tmx_errno` */
const char* tmx_strerr(void);

Behaviors

change the alloc and free functions of TMX and ZLIB and LibXml2:

/* Custom realloc and free function
   Please modify these values once before you use tmx_load */
extern void* (*tmx_alloc_func) (void *address, size_t len); /* realloc */
extern void  (*tmx_free_func ) (void *address);             /* free */

TMX can load images referenced in the map:

/* load/free tmx_image->resource_image, you should set this if you want
   the library to load/free images */
extern void* (*tmx_img_load_func) (const char *path);
extern void  (*tmx_img_free_func) (void *address);

Usage

#include <tmx.h>

int main(void) {
  tmx_map *map = tmx_load("path/map.tmx");
  if (!map) {
    tmx_perror("tmx_load");
    return 1;
  }
  /* ... */
  tmx_map_free(map);
  return 0;
}

See the dumper example (examples/dumper/dumper.c) for an in-depth usage of TMX.

Basic Allegro example: (examples/allegro/allegro.c)

Basic SDL example: (examples/sdl/sdl.c)

Thread Safety

Both LibXML2 and Zlib are thread safe. TMX is thread safe except its tmx_strerr function, which uses a global to store the error message.