Skip to main content

Tiled TMX Loader

Load Tiled's TMX files for use in PyGame.


Leif Theden
(bitcraft) 
Map loader for TMX Files
Leif Theden (bitcraft), 2011-2014
v3.19.3 - for python 2.7 and 3.3+

If you have any problems or suggestions, please open an issue on the github page.
I am also often lurking #pygame on freenode. Feel free to contact me.

released under the LGPL v3

===============================================================================

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.

Features:
    API with many handy functions
    Properties metadata for all native Tiled object types
    Point data for polygon and polyline objects
    Automatic flipping and rotation of tiles
    Supports base64, csv, gzip, zlib and uncompressed XML
    Image loading with pygame (works ok without pygame)

===============================================================================

Just data
---------

    >>> import pytmx
    >>> tmxdata = pytmx.TiledMap("map.tmx")


Load with Pygame Surfaces
-------------------------

    >>> from pytmx import load_pygame
    >>> tmxdata = 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)


Getting Object Properties
-------------------------
    >>> tmxdata = TiledMap('level1.tmx')
    >>> props = txmdata.get_tile_properties(x, y, layer)
    >>> props = tmxdata.get_layer_by_name("dirt").properties


Using Raw XML
-------------

It is possible to load TiledMap object from XML strings.

    >>> tmxdata = TiledMap.from_string(xml_string)

===============================================================================

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

===============================================================================

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

Changes

pygame 844 tiled 8 bitcraft 6 tmx 4 lib2d 1

Links

Home Page
https://github.com/bitcraft/PyTMX

Releases

Tiled TMX Loader v.13 — 20 Mar, 2012

Tiled TMX Loader v.11 — 20 Feb, 2012

Tiled TMX Loader v.14 — 10 May, 2012

Tiled TMX Loader v.15 — 31 May, 2012

Tiled TMX Loader 3.19.3 — 17 Sep, 2014

Pygame.org account Comments

  • Stephen 2012-03-27 14:00

    Just what I need...  thanks for your work !

  • Sam 2012-05-02 00:02

    This may or may not be a stupid question, but does anyone know how one would go by scrolling the map?

    Leif Theden 2012-05-10 01:06

    check out the new version, i added a scrolling demo

  • poz 2012-05-11 09:39

    I noticed a few error:

    It didnt handle tilesets with margin correctly. Yon can try to load the sample map "desert.tmx" that come with the Tiled
    Also couldnt handle transparent pixel. This also can be tested with "sewers.tmx" from the sample map in Tiled

    Leif Theden 2012-05-15 17:32

    i have fixed these issues in the github repository.  thanks for letting me know.

  • anon 2014-12-16 19:16

    So, if I wanted to display a .tmx map file in pygame, complete with properties such as objects and collision that I made in Tiled, which example would I use above? I feel stupid for asking but I've been trying for a full two days now to get this to work and I'm just getting nowhere. I usually don't ask these kinds of things, I just can't seem to get anywhere and I've seen plenty of people say how easy to use this is, so I must be missing something obvious/small.

    Leif Theden 2015-04-06 08:40

    pytmx is a map loader, and doesn't force you to render your map in a special way. the downside is, there is no built in renderer. if you want to render your map, you can follow the example in the apps folder (https://github.com/bitcraft/Py..., or use my ready made project pyscroll. To get tile info, you need to get the tile properties dict http://pytmx.readthedocs.org/e.... for objects, just query the object, then access them through object.properties. See the apps folder for API to get the objects, or the API docs at http://pytmx.readthedocs.org.

  • prometeh 2014-12-28 12:35

    hey bitcraft, how you doing? :)
    dude thanks for the great work, but to be honest there's only one thing that i think is missing here and that's "the documentation"...
    A nice code like these deserves to have a better document and a good tutorial, a few examples outside of the .py file, on a web page and a text about the concept of tiles in tiled and it's relations to your library, specially about implementing objects from tiled like sprites...
    it's been about a month that i'm working with your library and i just look at pytmx.py and try to figure it out, so hard man so hard, that makes me cry dude, a lil bit more comments in your code would highly appreciated also... beyond that buddy, thanks for your awesome code, all i'm saying is that the beginners like me need a bit more info, just my two cents.

    cheers.

    Leif Theden 2015-04-06 08:35

    Thanks for your interest and your comments. IMO, there are plenty of generic tutorials about making maps with Tiled and what tiles are, objects, etc. I have a few examples of how to use the library in the source...check out the apps folder. It demonstrates all the basic tasks that you can do with pytmx. Beyond that, I don't really have the time to make a step-step tutorial. The API is really quite simple and is all documented. pytmx.readthedocs.org has the API documentation. I guess you would say the audience of pytmx isn't new developers, it's more for people who already know what they need to do, and pytmx takes the pain out of parsing XML, variable type conversion, shape loading, properties, and of course image loading. When looking through the source, the important bits are in the docstrings. Hope that helps.

    If you need a more friendly way to use Tiled maps, please check out my other project pyscroll https://github.com/bitcraft/py... It has a friendlier way to load maps and use with pygame with the ScrollGroup class.

    Anonymous 2015-07-06 18:34

    It would be a great tool if you just didn't bitch off any criticism. Prometh is right. The documentation really is very poor.
    "IMO there are enough tutorials" unbelievable...

    Anonymouse 2015-08-05 17:53

    I hate when people bitch at a developer who is releasing his/her work to you for FREE. So shut up, use it, or don't. No one cares because you don't bring any value to the table.

  • Dan 2016-07-03 11:29

    can someone make a video tutorial i spent 3 days trying to get it to work