Simple TMX Library documentation — Simple TMX Library 1.9.1 documentation

# Simple TMX Library documentation

This library reads and writes the Tiled TMX format in a simple way. This is useful for map editors or generic level editors, and it’s also useful for using a map editor or generic level editor like Tiled to edit your game’s levels.

To load a TMX file, use `tmx.TileMap.load()`. You can then read the attributes of the returned `tmx.TileMap` object, modify the attributes to your liking, and save your changes with `tmx.TileMap.save()`. That’s it! Simple, isn’t it?

At the request of the developer of Tiled, this documentation does not explain in detail what each attribute means. For that, please see the TMX format specification, found here:

http://doc.mapeditor.org/reference/tmx-map-format/

## tmx.TileMap

class `tmx.` `TileMap`

  This class loads, stores, and saves TMX files.

  `version`

    The TMX format version.

  `orientation`

    Map orientation. Can be “orthogonal”, “isometric”, “staggered”, or “hexagonal”.

  `renderorder`

    The order in which tiles are rendered. Can be `"right-down"`, `"right-up"`, `"left-down"`, or `"left-up"`. Default is `"right-down"`.

  `width`

    The width of the map in tiles.

  `height`

    The height of the map in tiles.

  `tilewidth`

    The width of a tile.

  `tileheight`

    The height of a tile.

  `staggeraxis`

    Determines which axis is staggered. Can be “x” or “y”. Set to `None` to not set it. Only meaningful for staggered and hexagonal maps.

  `staggerindex`

    Determines what indexes along the staggered axis are shifted. Can be “even” or “odd”. Set to `None` to not set it. Only meaningful for staggered and hexagonal maps.

  `hexsidelength`

    Side length of the hexagon in hexagonal tiles. Set to `None` to not set it. Only meaningful for hexagonal maps.

  `backgroundcolor`

    A `Color` object indicating the background color of the map, or `None` if no background color is defined.

  `nextobjectid`

    The next available ID for new objects. Set to `None` to not set it.

  `properties`

    A list of `Property` objects indicating the map’s properties.

  `tilesets`

    A list of `Tileset` objects indicating the map’s tilesets.

  `layers`

    A list of `Layer`, `ObjectGroup`, and `ImageLayer` objects indicating the map’s tile layers, object groups, and image layers, respectively. Those that appear in this list first are rendered first (i.e. furthest in the back).

classmethod `TileMap.` `load`(fname)

  Load the TMX file with the indicated name and return a `TileMap` object representing it.

`TileMap.` `save`(fname, data_encoding='base64', data_compression=True)

  Save the object to the file with the indicated name.

  Arguments:

  - `data_encoding` – The encoding to use for layers. Can be `"base64"` or `"csv"`. Set to `None` for the default encoding (currently `"base64"`).
  - `data_compression` – Whether or not compression should be used on layers if possible (currently only possible for base64-encoded data).

## Other Classes

class `tmx.` `Color`(hex_string='#000000')
  `red`

    The red component of the color as an integer, where `0` indicates no red intensity and `255` indicates full red intensity.

  `green`

    The green component of the color as an integer, where `0` indicates no green intensity and `255` indicates full green intensity.

  `blue`

    The blue component of the color as an integer, where `0` indicates no blue intensity and `255` indicates full blue intensity.

  `alpha`

    The alpha transparency of the color as an integer, where `0` indicates full transparency and `255` indicates full opacity.

  `hex_string`

    The hex string representation of the color used by the TMX file. The format of the string is either `"#RRGGBB"` or `"#AARRGGBB"`. The hash at the beginning is optional.

class `tmx.` `Image`(format_=None, source=None, trans=None, width=None, height=None, data=None)
  `format`

    Indicates the format of image data if embedded. Should be an extension like `"png"`, `"gif"`, `"jpg"`, or `"bmp"`. Set to `None` to not specify the format.

  `source`

    The location of the image file referenced. If set to `None`, the image data is embedded.

  `trans`

    A `Color` object indicating the transparent color of the image, or `None` if no color is treated as transparent.

  `width`

    The width of the image in pixels; used for tile index correction when the image changes. If set to `None`, the image width is not explicitly specified.

  `height`

    The height of the image in pixels; used for tile index correction when the image changes. If set to `None`, the image height is not explicitly specified.

  `data`

    The image data if embedded, or `None` if an external image is referenced.

class `tmx.` `ImageLayer`(name, offsetx, offsety, opacity=1, visible=True, properties=None, image=None)
  `name`

    The name of the image layer.

  `offsetx`

    The x position of the image layer in pixels.

  `offsety`

    The y position of the image layer in pixels.

  `opacity`

    The opacity of the image layer as a value from 0 to 1.

  `visible`

    Whether or not the image layer is visible.

  `properties`

    A list of `Property` objects indicating the properties of the image layer.

  `image`

    An `Image` object indicating the image of the image layer.

class `tmx.` `Layer`(name, opacity=1, visible=True, offsetx=0, offsety=0, properties=None, tiles=None)
  `name`

    The name of the layer.

  `opacity`

    The opacity of the layer as a value from 0 to 1.

  `visible`

    Whether or not the layer is visible.

  `offsetx`

    Rendering offset for this layer in pixels.

  `offsety`

    Rendering offset for this layer in pixels.

  `properties`

    A list of `Property` objects indicating the properties of the layer.

  `tiles`

    A list of `LayerTile` objects indicating the tiles of the layer.

    The coordinates of each tile is determined by the tile’s index within this list. Exactly how the tiles are positioned is determined by the map orientation.

class `tmx.` `LayerTile`(gid, hflip=False, vflip=False, dflip=False)
  `gid`

    The global ID of the tile. A value of `0` indicates no tile at this position.

  `hflip`

    Whether or not the tile is flipped horizontally.

  `vflip`

    Whether or not the tile is flipped vertically.

  `dflip`

    Whether or not the tile is flipped diagonally (X and Y axis swapped).

class `tmx.` `Object`(name, type_, x, y, width=0, height=0, rotation=0, gid=None, visible=True, properties=None, ellipse=False, polygon=None, polyline=None, id_=None)
  `id`

    Unique ID of the object as a string if set, or `None` otherwise.

  `name`

    The name of the object. An arbitrary string.

  `type`

    The type of the object. An arbitrary string.

  `x`

    The x coordinate of the object in pixels. This is the left edge of the object in orthogonal orientation, and the center of the object otherwise.

  `y`

    The y coordinate of the object in pixels. This is the bottom edge of the object.

  `width`

    The width of the object in pixels.

  `height`

    The height of the object in pixels.

  `rotation`

    The rotation of the object in degrees clockwise.

  `gid`

    The tile to use as the object’s image. Set to `None` for no reference to a tile.

  `visible`

    Whether or not the object is visible.

  `properties`

    A list of `Property` objects indicating the object’s properties.

  `ellipse`

    Whether or not the object should be an ellipse.

  `polygon`

    A list of coordinate pair tuples relative to the object’s position indicating the points of the object’s representation as a polygon. Set to `None` to not represent the object as a polygon.

  `polyline`

    A list of coordinate pair tuples relative to the object’s position indicating the points of the object’s representation as a polyline. Set to `None` to not represent the object as a polyline.

class `tmx.` `ObjectGroup`(name, color=None, opacity=1, visible=True, offsetx=0, offsety=0, draworder=None, properties=None, objects=None)
  `name`

    The name of the object group.

  `color`

    A `Color` object indicating the color used to display the objects in this group. Set to `None` for no color definition.

  `opacity`

    The opacity of the object group as a value from 0 to 1.

  `visible`

    Whether or not the object group is visible.

  `offsetx`

    Rendering offset for this layer in pixels.

  `offsety`

    Rendering offset for this layer in pixels.

  `draworder`

    Can be “topdown” or “index”. Set to `None` to not define this.

  `properties`

    A list of `Property` objects indicating the object group’s properties

  `objects:`

    A list of `Object` objects indicating the object group’s objects.

class `tmx.` `Property`(name, value)
  `name`

    The name of the property.

  `value`

    The value of the property.

    The following types are specially recognized by the TMX format and preserved when saving:

    - Integers
    - Floats
    - Booleans
    - `Color` objects
    - `pathlib.PurePath` objects

    Any other type is implicitly converted to and stored as a string when the TMX file is saved.

class `tmx.` `TerrainType`(name, tile, properties=None)
  `name`

    The name of the terrain type.

  `tile`

    The local tile ID of the tile that represents the terrain visually.

  `properties`

    A list of `Property` objects indicating the terrain type’s properties.

class `tmx.` `Tile`(id_, terrain=None, probability=None, properties=None, image=None, animation=None)
  `id`

    The local tile ID within its tileset.

  `terrain`

    Defines the terrain type of each corner of the tile, given as comma-separated indexes in the list of terrain types in the order top-left, top-right, bottom-left, bottom-right. Leaving out a value means that corner has no terrain. Set to `None` for no terrain.

  `probability`

    A percentage indicating the probability that this tile is chosen when it competes with others while editing with the terrain tool. Set to `None` to not define this.

  `properties`

    A list of `Property` objects indicating the tile’s properties.

  `image`

    An `Image` object indicating the tile’s image. Set to `None` for no image.

  `animation`

    A list of `Frame` objects indicating this tile’s animation. Set to `None` for no animation.

class `tmx.` `Tileset`(firstgid, name, tilewidth, tileheight, source=None, spacing=0, margin=0, xoffset=0, yoffset=0, tilecount=None, columns=None, properties=None, image=None, terraintypes=None, tiles=None)
  `firstgid`

    The first global tile ID of this tileset (this global ID maps to the first tile in this tileset).

  `name`

    The name of this tileset.

  `tilewidth`

    The (maximum) width of the tiles in this tileset.

  `tileheight`

    The (maximum) height of the tiles in this tileset.

  `source`

    The external TSX (Tile Set XML) file to store this tileset in. If set to `None`, this tileset is stored in the TMX file.

  `spacing`

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

  `margin`

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

  `xoffset`

    The horizontal offset of the tileset in pixels (positive is right).

  `yoffset`

    The vertical offset of the tileset in pixels (positive is down).

  `tilecount`

    The number of tiles in this tileset. Set to `None` to not specify this.

  `columns`

    The number of tile columns in the tileset. Set to `None` to not specify this.

  `properties`

    A list of `Property` objects indicating the tileset’s properties.

  `image`

    An `Image` object indicating the tileset’s image. Set to `None` for no image.

  `terraintypes`

    A list of `TerrainType` objects indicating the tileset’s terrain types.

  `tiles`

    A list of `Tile` objects indicating the tileset’s tile properties.

## Functions

`tmx.` `data_decode`(data, encoding, compression=None)

  Decode encoded data and return a list of integers it represents.

  This is a low-level function used internally by this library; you don’t typically need to use it.

  Arguments:

  - `data` – The data to decode.
  - `encoding` – The encoding of the data. Can be `"base64"` or `"csv"`.
  - `compression` – The compression method used. Valid compression methods are `"gzip"` and `"zlib"`. Set to `None` for no compression.

`tmx.` `data_encode`(data, encoding, compression=True)

  Encode a list of integers and return the encoded data.

  This is a low-level function used internally by this library; you don’t typically need to use it.

  Arguments:

  - `data` – The list of integers to encode.
  - `encoding` – The encoding of the data. Can be `"base64"` or `"csv"`.
  - `compression` – Whether or not compression should be used if supported.

## Indices and tables

- Index
- Module Index
- Search Page