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_user_data
user_data
¶ Use that member to store your own data, see
tmx_user_data
.
-
char *
-
tmx_layer
¶ Layer data.
-
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 intmx_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.
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_layer *
group_head
¶ This layer is a group of layer, pointer to the head of a linked list of children layers.
-
int32_t *
-
union
-
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.
-
double
-
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.
-
int
-
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 istmx_tileset.tilecount
.
-
char *
-
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
.
-
unsigned int
-
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
.
-
unsigned int
-
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 intmx_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.
-
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.
-
unsigned int
-
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.
-
double **
-
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.
-
char *
-
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.
-
int
-
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
.
-
char *
-
tmx_properties
¶ This type is private, you can manipulate it using the
tmx_get_property()
andtmx_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 intmx_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.
-
int
-
union
-
char *