For Python 2.7 and 3.3+
This is the most up-to-date version of PyTMX available and works with Python 2.7 and 3.3 with no changes to the source code. Please use this branch for all new PyTMX projects.
If you have any problems or suggestions, please open an issue. I am also often lurking #pygame on freenode. Feel free to contact me.
Requires the six module.
Released under the LGPL v3
See the "apps" folder for example use.
09/14/14 - Merge python3 branch. Now 100% compatible with 2.7 and 3.3+
07/26/14 - New python3/2 release. Check it out in the python3 branch.
05/29/14 - Added support for rotated objects and floating point
04/04/14 - New Six Branch created
02/28/14 - Image layer support, object points changed, new test.py!
02/24/14 - New Python 3 Support: see python3 branch
02/06/14 - Python 3 support coming soon
PyTMX is a map loader for python/pygame designed for games. It provides smart tile loading with a fast and efficient storage base. Not only will does it correctly handle most Tiled object types, it also will load metadata for them, so you can modify your maps and objects in Tiled, instead of modifying your source code.
Because PyTMX was built with games in mind, it differs slightly from Tiled in a few minor aspects:
- Layers not aligned to the grid are not supported.
- Some object metadata attribute names are not supported (see below)
PyTMX strives to balance performance and flexibility. Feel free to use the classes provided in pytmx.py as superclasses for your own maps, or simply load the data with PyTMX and copy the data into your own classes with the api.
Finally, there is no save feature. Once the map is loaded, it will be up to you to provide a way to save changes to the map. I've used the pickle module with good results.
For bugs or feature requests, please use the issues feature of github. For all other general questions, join me on IRC at freennode.net #pygame.
Design Goals and Features
- API with many handy functions
- Memory efficient and performant
- Loads data, "properties" metadata, and images from Tiled's TMX format
- Supports base64, csv, gzip, zlib and uncompressed XML
- Properties for all native Tiled object types
- Point data for polygon and polyline objects
- Automatic flipping and rotation of tiles
- Built-in image loading with pygame (will work without images as well)
Why use PyTMX?
PyTMX is efficient:
- Only the tiles used on a map are loaded into memory
- Map information is stored as integers (16 bit), not python objects (32+kb)
- Extensive use of generators and iterators make it easy on memory
- Code is designed for compact size and readability
PyTMX is flexible:
- Supports all major Tiled features and object types
- PyTMX data classes can be extended
- Does not force you to render data in any particular way
- Includes many checks to give useful debugging information
- pygame is supported, but not required
PyTMX is supported:
- GitHub hosting allows for community participation
- I have kept PyTMX current with new versions of Tiled since v.7
PyTMX is usable:
- Liberal LGPL license means you can use PyTMX for your project
Install from pip
pip install pytmx
You can also manually install it
python setup.py install
import pytmx tmx_data = pytmx.TiledMap('map.tmx')
Load with Pygame Images:
from pytmx import load_pygame tmx_data = load_pygame('map.tmx')
The loader will correctly convert() or convert_alpha() each tile image, so you don't have to worry about that after you load the map.
Getting the Tile Surface
image = tmx_data.get_tile_image(x, y, layer) screen.blit(image, position)
Tile, Object, and Map Properties
Properties are any key/value data added to an object/map/layer in Tiled through the properties dialog. Tile properties are accessed through the the parent map object:
tmxdata = TiledMap('level1.tmx') props = txmdata.get_tile_properties(x, y, layer) props = tmxdata.get_tile_properties_by_gid(tile_gid)
All other objects, including the map, layer, objects, etc. are in an dict attribute called "properties":
tmx_data = TiledMap('level1.tmx') tmx_data.properties['name'] for layer in tmxdata.visible_layers: layer.properties['movement_speed']
I have another repo with a working demo of a proper scrolling map using Tiled maps. Please feel free to test drive it. It isn't limited to Tiled maps, you can use any data structure you want, as long as PyGame is used.
If you use "properties" for any of the following object types, you cannot use any of these words as a name for your property. A ValueError will be raised if a Tile Object attempts to use a reserved name.
In summary: don't use the following names when adding metadata in Tiled.
As of 0.8.1, these values are:
map: version, orientation, width, height, tilewidth, tileheight
properties, tileset, layer, objectgroup
tileset: firstgid, source, name, tilewidth, tileheight, spacing, margin,
image, tile, properties
tile: id, image, properties
layer: name, x, y, width, height, opacity, properties, data
objectgroup: name, color, x, y, width, height, opacity, object, properties
object: name, type, x, y, width, height, gid, properties, polygon,
*** Please see the TiledMap class source for more api information. ***
Example version: X.Y.Z
- X: 2 for python 2, 3 for python 3 and 2
- Y: major release. for new features or api change
- Z: minor release. for bug fixes related to last release
Running the Tests
Install the nose package with pip then from the root of the project run:
The 16x16 overworld tiles were created by MrBeast at opengameart.org. CC-BY 3.0
- If I missed your attribution, please let me know.