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_obj_alignment¶

Controls the alignment of tiles. When unspecified, tile objects use OA_BOTTOMLEFT in orthogonal mode and OA_BOTTOM in isometric mode (see tmx_map_orient).

Object align	Description
OA_NONE	Object alignment is unspecified.
OA_TOP	Top.
OA_LEFT	Left.
OA_BOTTOM	Bottom.
OA_RIGHT	Right.
OA_TOPLEFT	Top-Left.
OA_TOPRIGHT	Top-Right.
OA_BOTTOMLEFT	Bottom-Left.
OA_BOTTOMRIGHT	Bottom-Right.

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.
PT_OBJECT	An object, use value.object_id.
PT_CUSTOM	Custom type, use value.properties.

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.
HA_JUSTIFY	Justify.

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.

enum tmx_tile_render_size¶

The size to use when rendering tiles.

Render size	Description
TRS_NONE	In case of error, or unknown render size.
TRS_TILE	Tile size in its tileset
TRS_GRID	Tile grid size of the map

enum tmx_fill_mode¶

The fill mode to use when rendering tiles scaled.

Fill mode	Description
FM_NONE	In case of error, or unknown fill mode.
FM_STRETCH	Stretch to fit.
FM_PRESERVE_ASPECT_FIT	Preserve aspect ratio.

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.

char *format_version¶: The TMX format version, eg: “1.0”.

char *class_type¶: Class of the map (user defined).

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.

int parallaxoriginx¶: X coordinate of the parallax origin in pixels.

int parallaxoriginy¶: Y coordinate of the parallax origin 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.

int id¶: A map-unique ID of the layer.

char *name¶: Name of the layer (user defined).

char *class_type¶: Class 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.

uint32_t tintcolor¶: Optional tint colour, encoded in an integer, 4 bytes: ARGB.

int repeatx¶: Boolean, whether the image drawn by this layer is repeated along the X axis. (image layers only)

int repeaty¶: Boolean, whether the image drawn by this layer is repeated along the Y axis. (image layers only)

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).

char *class_type¶: Class 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.

enum tmx_obj_alignment¶: Controls the alignment of tiles, see tmx_obj_alignment.

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).

enum tmx_tile_render_size¶: Controls the size of tiles, see tmx_tile_render_size.

enum tmx_fill_mode¶: Controls how tiles scale, see tmx_fill_mode.

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 this tile has its own image.

unsigned int ul_y¶: Upper-left y coordinate of this tile on the tileset image, irrelevant if this tile has its own image.

unsigned int width¶: Witdh of this tile on the tileset image, irrelevant if this tile has its own image.

unsigned int height¶: Height of this tile on the tileset image, irrelevant if 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).

char *propertytype¶: The name of the custom property type (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.

int object_id¶: Object unique identifier, see tmx_find_object_by_id().

tmx_properties *properties¶: Members of a custom property type.

union tmx_user_data¶

int integer¶: Integer.

float decimal¶: Float.

void *pointer¶: Pointer.