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};
enum tmx_map_renderorder {R_NONE, R_RIGHTDOWN, R_RIGHTUP, R_LEFTDOWN, R_LEFTUP};
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;

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

struct _tmx_img { /* <image> */
        char *source;
        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_image *image;
        tmx_object *collision;

        unsigned int animation_len;
        tmx_anim_frame *animation;

        tmx_property *properties;
        tmx_tile *next;
};

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 */
        tmx_image *image;
        tmx_property *properties;
        tmx_tile *tiles;
        tmx_tileset *next;
};

struct _tmx_obj { /* <object> */
        char *name;
        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;
        tmx_property *properties;
        tmx_object *next;
};

struct _tmx_objgr { /* <objectgroup> */
        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 x_offset, y_offset; /* For image layers */

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

        void *user_data; /* not freed by tmx_free ! */
        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;
        int backgroundcolor; /* bytes : RGB */
        enum tmx_map_renderorder renderorder;

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

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 tileset and the upper-left coordinate on the tileset
   of the tile associated with this gid, returns NULL if it fails */
tmx_tileset* tmx_get_tileset(tmx_map *map, unsigned int gid, unsigned int *x, unsigned int *y);

/* 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_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.