PyTMX

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.

News

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

Introduction

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.

Documentation

http://pytmx.readthedocs.org/

Getting Help

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

Installation

Install from pip

pip install pytmx

You can also manually install it

python setup.py install

Basic use:

Just data:

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']

Scrolling Demo

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.

https://github.com/bitcraft/pyscroll

Reserved Names

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,
polyline, image

*** Please see the TiledMap class source for more api information. ***

Version Numbering

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:

    nosetests

Artwork Attributions

The 16x16 overworld tiles were created by MrBeast at opengameart.org. CC-BY 3.0

If I missed your attribution, please let me know.

mpyatishev/PyTMX