The Data Structure

libTMX loads maps into a plain old C datastructure, this page describes that data structure thoroughly. libTMX reuse names from the TMX Format for all its structures and structure members.

Definitions

Tiled use the 3 leftmost bits of the GID to store if a tile is flipped.

TMX_FLIPPED_HORIZONTALLY

Used to tell if a cell has the horizontal flip flag set:

int is_horizontally_flipped = cell & TMX_FLIPPED_HORIZONTALLY;
TMX_FLIPPED_VERTICALLY

Used to tell if a cell has the vertical flip flag set:

int is_horizontally_flipped = cell & TMX_FLIPPED_VERTICALLY;
TMX_FLIPPED_DIAGONALLY

Used to tell if a cell has the diagonal flip flag set:

int is_horizontally_flipped = cell & TMX_FLIPPED_DIAGONALLY;
TMX_FLIP_BITS_REMOVAL

Used to remove all flip flags:

int gid   = cell &  TMX_FLIP_BITS_REMOVAL;
int flags = cell & ~TMX_FLIP_BITS_REMOVAL;

Enumerations

enum tmx_map_orient

Map orientation (orthogonal, isometric, hexagonal, …).

Map orientation Description
O_NONE In case of error, or unknown map orientation.
O_ORT Orthogonal map.
O_ISO Isometric map.
O_STA Staggered map.
O_HEX Hexagonal map.
enum tmx_map_renderorder

How the tile layers should be drawn, the order in which tiles on tile layers are rendered. This is especially usefull if you’re drawing overlapping tiles (see the perspective_walls.tmx example that ships with Tiled).

Map renderorder Description
R_NONE In case of error, or unknown map renderorder.
R_RIGHTDOWN Draw tiles from right to left, top to bottom.
R_RIGHTUP Draw tiles from right to left, bottom to top.
R_LEFTDOWN Draw tiles from left to right, top to bottom.
R_LEFTUP Draw tiles from left to right, bottom to top.
enum tmx_stagger_index

For staggered and hexagonal maps, determines whether the “even” or “odd” indexes along the staggered axis are shifted.

Stagger index Description
SI_NONE In case of error, or unknown stagger index.
SI_EVEN Odd.
SI_ODD Even.
enum tmx_stagger_axis

For staggered and hexagonal maps, determines which axis (“x” or “y”) is staggered.

Stagger axis Description
SA_NONE In case of error, or unknown stagger axis.
SA_X x axis.
SA_Y y axis.
enum tmx_layer_type

Type of layer.

Layer type Description
L_NONE In case of error, or unknown layer type.
L_LAYER Tile layer type, use content.gids.
L_OBJGR Objectgroup layer type, use content.objgr.
L_IMAGE Image layer type, use content.image.
L_GROUP Group of layer layer type, use content.group_head.
enum tmx_objgr_draworder

Whether the objects are drawn according to the order of appearance (“index”) or sorted by their y-coordinate (“topdown”).

Object draworder Description
G_NONE In case of error, or unknown draw order.
G_INDEX Draw objects as they are ordered in the linked-list.
G_TOPDOWN Draw objects sorted by their y-coordinate, objects must then be reordered by their y-coordinate.
enum tmx_obj_type

Type of object.

Object type Description
OT_NONE In case of error, or unknown object type.
OT_SQUARE Square, use members x, y, width and height.
OT_POLYGON Polygon, use content.shape.
OT_POLYLINE Polyline, use content.shape.
OT_ELLIPSE Ellipse, use members x, y, width (horizontal radius) and height (vertical radius)
OT_TILE Tile, use content.gid.
OT_TEXT Text, use content.text.
OT_POINT Point, use members x, y.
enum tmx_property_type

Type of property.

Property type Description
PT_NONE In case of error, or unknown property type.
PT_INT Integer, use value.integer.
PT_FLOAT Float, use value.decimal.
PT_BOOL Boolean, use value.boolean.
PT_STRING String, use value.string.
PT_COLOR Color, use value.color (RGBA encoded in an integer).
PT_FILE Path to a file, use value.file.
enum tmx_horizontal_align

Horizontal alignment of the text within the object.

Text align Description
HA_NONE In case of error, or unknown text align.
HA_LEFT Left.
HA_CENTER Center.
HA_RIGHT Right.
enum tmx_vertical_align

Vertical alignment of the text within the object.

Text align Description
VA_NONE In case of error, or unknown text align.
VA_TOP Top.
VA_CENTER Center.
VA_BOTTOM Bottom.

Data Structures

The datastructure is a tree, just like the source XML document, from the root (tmx_map) you can access everything.

tmx_map

The root of the datastructure.

enum tmx_map_orient orient

Map orientation, see tmx_map_orient.

unsigned int width

The width of the map in cells.

unsigned int height

The height of the map in cells.

unsigned int tile_width

The width of tiles in pixels.

unsigned int tile_height

The height of tiles in pixels.

enum tmx_stagger_index stagger_index

Stagger index, see tmx_stagger_index.

enum tmx_stagger_axis stagger_axis

Stagger axis, see tmx_stagger_axis.

int hexsidelength

Only for hexagonal maps. Determines the width or height (depending on the staggered axis) of the tile’s edge, in pixels.

unsigned int backgroundcolor

Global background colour, encoded in an integer, 4 bytes: ARGB.

enum tmx_map_renderorder renderorder

Map render order, see tmx_map_renderorder.

tmx_properties *properties

Properties of the map, see tmx_properties.

tmx_tileset_list *ts_head

Head of the tileset linked list, see tmx_.

tmx_layer *ly_head

Head of the layers linked list, see tmx_layer.

unsigned int tilecount

length of the tiles array described below.

tmx_tile **tiles

GID indexed tile array (array of pointers to tmx_tile).

tmx_user_data user_data

Use that member to store your own data, see tmx_user_data.

tmx_layer

Layer data.

char *name

Name of the layer (user defined).

double opacity

Opacity of the layer (0.0 = transparent, 1.0 = opaque).

int visible

Boolean, visibility of the layer (0 = false, any other value = true).

int offsetx

Horizontal offset in pixels, a positive value shifts the layer to the right.

int offsety

Vertical offset in pixels, a positive value shifts the layer down.

enum tmx_layer_type type

Type of layer, see tmx_layer_type, tells you which member to use in tmx_layer.content.

union layer_content content

Content of the layer, as there are several types of layers (tile, object, image, …), the content is different for each type.

Note

You should check the value of member tmx_layer.type to use the correct union member.

union layer_content
int32_t *gids

Array of layer cells.

Warning

GID=0 (zero) is a special GID which means that this cell is empty!

Example: iterate on all cells, from left to right, top to bottom:

for(int cell_y = 0; cell_y < map->height; cell_y++) {
   for(int cell_x = 0; cell_x < map->width; cell_x++) {
      int32_t cell = layer->content.gids[cell_y * map->width + cell_x];
      int32_t GID = cell & TMX_FLIP_BITS_REMOVAL;
      /* Draw tile operation... */
   }
}

Example: Direct access to the cell:

int32_t get_cell_at(tmx_layer *layer, unsigned int map_width, unsigned int x, unsigned int y) {
   return layer->content.gids[y * map_width + x];
}
tmx_object_group *objgr

This layer is an object group.

tmx_image *image

This layer is an image layer.

tmx_layer *group_head

This layer is a group of layer, pointer to the head of a linked list of children layers.

tmx_user_data user_data

Use that member to store your own data, see tmx_user_data.

tmx_properties *properties

Properties of the layer, see tmx_properties.

tmx_layer *next

Next element of the linked list, if NULL then you reached the last element.

tmx_tileset_list

In map tileset data.

int is_embedded

Private member used internally to free this tileset (depends on the usage of a resource manager).

unsigned int firstgid

GID (Global ID) of the first tile in this tileset.

char *source

In case of external tileset, path to the TSX file (should be relative to the location of this map on the file system), NULL otherwise.

tmx_tileset *tileset

Tileset data, see tmx_tileset.

tmx_tileset_list *next

Next element of the linked list, if NULL then you reached the last element.

tmx_tileset

Tileset data, usually loaded from an external TSX file.

char *name

Name of the tileset (user defined).

unsigned int tile_width

The width of tiles in pixels.

unsigned int tile_height

The height of tiles in pixels.

unsigned int spacing

The spacing in pixels between the tiles in this tileset (applies to the tileset image).

unsigned int margin

The margin around the tiles in this tileset (applies to the tileset image).

int x_offset

Horizontal offset in pixels, a positive value shifts the drawing of tiles to the right.

int y_offset

Vertical offset in pixels, a positive value shifts the drawing of tiles down.

unsigned int tilecount

The number of tiles in this tileset, length of the tmx_tileset.tiles array.

tmx_image *image

Image for this tileset, may be NULL if this tileset is a collection of single images (one image per tile).

tmx_user_data user_data

Use that member to store your own data, see tmx_user_data.

tmx_properties *properties

Properties of the tileset, see tmx_properties.

tmx_tile *tiles

Array of tmx_tile, its length is tmx_tileset.tilecount.

tmx_tile

Tile data.

unsigned int id

LID (Local ID) of the tile.

To compute the GID in a map from the LID from a tileset, add that LID with the tmx_tileset_list.firstgid of its in map tileset reference.

unsigned int GID = tileset_list->firstgid + LID;
tmx_tileset *tileset

The owner of this tile, see tmx_tileset.

unsigned int ul_x

Upper-left x coordinate of this tile on the tileset image, irrelevant if the this tile has its own image.

unsigned int ul_y

Upper-left y coordinate of this tile on the tileset image, irrelevant if the this tile has its own image.

tmx_image *image

Image for this tile, may be NULL if this tileset use a single image (atlas) for all tiles.

tmx_object *collision

Collision shape of this tile, may be NULL (optional).

unsigned int animation_len

Length of the tmx_tile.animation array.

tmx_anim_frame *animation

Array of tmx_anim_frame animation frames.

char *type

Type (user defined).

tmx_properties *properties

Properties of the tile, see tmx_properties.

tmx_user_data user_data

Use that member to store your own data, see tmx_user_data.

tmx_object_group
unsigned int color

Colour of the object group, encoded in an integer, 4 bytes: ARGB.

enum tmx_objgr_draworder draworder

Draw order, see tmx_objgr_draworder.

tmx_object *head

Head of the object linked list, see tmx_object.

tmx_object

Object data.

unsigned int id

Object ID.

enum tmx_obj_type obj_type

Type of object, see tmx_obj_type, tells you which member to use in tmx_object.content.

double x

Upper-left x coordinate of the object in pixels.

double y

Upper-left y coordinate of the object in pixels.

double width

Width of the object in pixels.

double height

Height of the object in pixels.

union object_content content

Content of the object, as there are several types of objects (tile, square, polygon, …) the content is different for each type.

Note

You should check the value of member tmx_object.type to use the correct union member.

union object_content
int gid

GID of the tile for Tile objects.

tmx_shape *shape

List of points for polygon and polyline objects, see tmx_shape.

tmx_text *text

Text and formatting for text objects, see tmx_text.

int visible

Boolean, visibility of the object (0 = false, any other value = true).

double rotation

Rotation in degrees clockwise.

char *name

Name (user defined).

char *type

Type (user defined).

tmx_template *template

Optional object template, holds default values that this object overrides.

tmx_properties *properties

Properties of the object, see tmx_properties.

tmx_object *next

Next element of the linked list, if NULL then you reached the last element.

tmx_shape

Points for object types Polyline and Polygon.

double **points

Array of points (x,y coordinate couples).

Usage:

double x, y;
for(int it = 0; it < shape->points_len; it++) {
  x = shape->point[it][0];
  y = shape->point[it][1];
  /* Draw operation... */
}
int points_len

Length of the tmx_shape.points array.

tmx_text

For object type Text.

char *fontfamily

Name of font to use.

int pixelsize

Size of font in pixels.

unsigned int color

Colour of the text, encoded in an integer, 4 bytes: ARGB.

int wrap

Boolean, word wrapping (0 = false, any other value = true).

int bold

Boolean, bold text (0 = false, any other value = true).

int italic

Boolean, italic text (0 = false, any other value = true).

int underline

Boolean, underlined text (0 = false, any other value = true).

int strikeout

Boolean, striked out text (0 = false, any other value = true).

int kerning

Boolean, use kerning (0 = false, any other value = true).

enum tmx_horizontal_align halign

Horizontal alignment of text, see tmx_horizontal_align.

enum tmx_vertical_align valign

Vertical alignment of text, see tmx_vertical_align.

char *text

String to render.

tmx_template

Object template.

int is_embedded

Private member used internally to free this object template.

tmx_tileset_list *tileset_ref

Head of the linked list of templates referenced by this object template, may be NULL.

tmx_object *object

Template object.

tmx_anim_frame
unsigned int tile_id

LID of the tmx_tile to be drawn during this frame.

unsigned int duration

Duration of this frame in milliseconds.

tmx_image
char *source

Path to the image file (user defined, should be relative to the location of this map on the file system).

unsigned int trans

Transparency colour, encoded in an integer, 3 bytes: RGB.

int uses_trans

Boolean, if the transparency should (0 = false, any other value = true).

unsigned long width

The image width in pixels.

unsigned long height

The image height in pixels.

void *resource_image

NULL unless the Image Autoload/Autofree callback functions are set, then holds the value returned by tmx_img_load_func.

tmx_properties

This type is private, you can manipulate it using the tmx_get_property() and tmx_property_foreach() functions.

tmx_property
char *name

Name of the property (user defined).

enum tmx_property_type type

Type of the property (String, Boolean, Path, …), see tmx_property_type, tells you which member to use in tmx_property.value.

union tmx_property_value value

Value of this property.

Note

You should check the value of member tmx_property.type to use the correct union member.

union tmx_property_value
int integer

Integer.

int boolean

Boolean (0 = false, any other value = true).

float decimal

Float.

char *string

String.

char *file

String (path).

unsigned int color

Colour, encoded in an integer, 4 bytes: ARGB.

union tmx_user_data
int integer

Integer.

float decimal

Float.

void *pointer

Pointer.