pytmx package¶

Submodules¶

pytmx.pytmx module¶

This file is part of pytmx.

pytmx is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

pytmx is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with pytmx. If not, see <http://www.gnu.org/licenses/>.

class pytmx.pytmx.TiledElement[source]¶

Bases: object

Base class for all pytmx types

allow_duplicate_names = False¶

classmethod from_xml_string(xml_string: str) → pytmx.pytmx.TiledElement[source]¶

Return a TiledElement object from a xml string

Parameters:	xml_string – string containing xml data

class pytmx.pytmx.TiledMap(filename: Optional[str] = None, image_loader=<function default_image_loader>, **kwargs)[source]¶

Bases: pytmx.pytmx.TiledElement

Contains the layers, objects, and images from a Tiled TMX map

This class is meant to handle most of the work you need to do to use a map.

add_layer(layer: Union[pytmx.pytmx.TiledTileLayer, pytmx.pytmx.TiledImageLayer, pytmx.pytmx.TiledGroupLayer, pytmx.pytmx.TiledObjectGroup]) → None[source]¶: Add a layer to the map

add_tileset(tileset: pytmx.pytmx.TiledTileset) → None[source]¶: Add a tileset to the map

get_layer_by_name(name: str)[source]¶

Return a layer by name

Parameters:	name – Name of layer. Case-sensitive.
Raises:	`ValueError` – if layer by name does not exist

get_object_by_id(obj_id: int) → pytmx.pytmx.TiledObject[source]¶

Find an object by the object id

Parameters:	obj_id – ID of the object, from Tiled

get_object_by_name(name) → pytmx.pytmx.TiledObject[source]¶

Find an object by name, case-sensitive

Parameters:	name – name of object

get_tile_colliders() → Iterable[Tuple[int, List[Dict[KT, VT]]]][source]¶: Return iterator of (gid, dict) pairs of tiles with colliders

get_tile_gid(x: int, y: int, layer: int) → int[source]¶

Return the tile image GID for this location

Parameters:	x – x coordinate y – y coordinate layer – layer number
Returns:	the image object type will depend on the loader (ie. pygame surface)
Raises:	`ValueError` – if coordinates are out of bounds

get_tile_image(x: int, y: int, layer: int)[source]¶

Return the tile image for this location

Parameters:	x – x coordinate y – y coordinate layer – layer number
Returns:	the image object type will depend on the loader (ie. pygame surface)
Raises:	`TypeError` – if coordinates are not integers `ValueError` – if the coordinates are out of bounds, or GID not found

get_tile_image_by_gid(gid: int)[source]¶

Return the tile image for this location

Parameters:	gid – GID of image
Returns:	the image object type will depend on the loader (ie. pygame surface)
Raises:	`TypeError` – if gid is not an integer `ValueError` – if there is no image for this GID

get_tile_locations_by_gid(gid: int) → Iterable[Tuple[int, int, int]][source]¶

Search map for tile locations by the GID

Return (int, int, int) tuples, where the layer is index of the visible tile layers.

Note: Not a fast operation. Cache results if used often.

Parameters:	gid – GID to be searched for

get_tile_properties(x: int, y: int, layer: int) → Optional[Dict[KT, VT]][source]¶

Return the tile image GID for this location

Parameters:	x – x coordinate y – y coordinate layer – layer number
Returns:	dict of the properties for tile in this location, or None
Raises:	`ValueError` – if coordinates are out of bounds

get_tile_properties_by_gid(gid: int) → Optional[Dict[KT, VT]][source]¶

Get the tile properties of a tile GID

Parameters:	gid – GID
Returns:	dict of properties for GID, or None

get_tile_properties_by_layer(layer: int)[source]¶

Get the tile properties of each GID in layer

Parameters:	layer – layer number

get_tileset_from_gid(gid: int) → pytmx.pytmx.TiledTileset[source]¶

Return tileset that owns the gid

Note: this is a slow operation, so if you are expecting to do this: often, it would be worthwhile to cache the results of this.

Parameters:	gid – gid of tile image
Raises:	`ValueError` – if the tileset for gid is not found

map_gid(tiled_gid: int) → Optional[List[int]][source]¶

Used to lookup a GID read from a TMX file’s data

Parameters:	tiled_gid – GID that is found in TMX data

map_gid2(tiled_gid: int) → List[Tuple[int, Optional[int]]][source]¶: WIP. need to refactor the gid code

objectgroups¶: Return iterator of all object groups

objects¶: Return iterator of all the objects associated with this map

parse_xml(node: xml.etree.ElementTree.Element)[source]¶

Parse a map from ElementTree xml node

Parameters:	node – ElementTree xml node to parse

register_gid(tiled_gid: int, flags: Optional[pytmx.pytmx.TileFlags] = None) → int[source]¶

Used to manage the mapping of GIDs between the tmx and pytmx

Parameters:	tiled_gid – GID that is found in TMX data flags – TileFlags
Returns:	New or existing GID for pytmx use

reload_images() → None[source]¶

Load or reload the map images from disk

This method will use the image loader passed in the constructor to do the loading or will use a generic default, in which case no images will be loaded.

set_tile_properties(gid: int, properties: dict) → None[source]¶

Set the tile properties of a tile GID

Parameters:	gid – GID properties – python dict of properties for GID

visible_layers¶: Return iterator of Layer objects that are set ‘visible’

visible_object_groups¶: Return iterator of object group indexes that are set ‘visible’

visible_tile_layers¶: Return iterator of layer indexes that are set ‘visible’

class pytmx.pytmx.TiledTileset(parent, node)[source]¶

Bases: pytmx.pytmx.TiledElement

Represents a Tiled Tileset

External tilesets are supported. GID/ID’s from Tiled are not guaranteed to be the same after loaded.

parse_xml(node)[source]¶

Parse a Tileset from ElementTree xml element

A bit of mangling is done here so that tilesets that have external TSX files appear the same as those that don’t

Parameters:	node – node to parse

class pytmx.pytmx.TiledTileLayer(parent, node)[source]¶

Bases: pytmx.pytmx.TiledElement

Represents a TileLayer

To just get the tile images, use TiledTileLayer.tiles()

iter_data() → Iterable[Tuple[int, int, int]][source]¶

Yields X, Y, GID tuples for each tile in the layer

Returns:	Iterator of X, Y, GID tuples for each tile in the layer

parse_xml(node: xml.etree.ElementTree.Element)[source]¶

Parse a Tile Layer from ElementTree xml node

Parameters:	node – node to parse

tiles()[source]¶

Yields X, Y, Image tuples for each tile in the layer

Returns:	Iterator of X, Y, Image tuples for each tile in the layer

class pytmx.pytmx.TiledObject(parent, node)[source]¶

Bases: pytmx.pytmx.TiledElement

Represents a any Tiled Object

Supported types: Box, Ellipse, Tile Object, Polyline, Polygon

apply_transformations()[source]¶: Return all points for object, taking in account rotation

as_points¶

image¶

Image for the object, if assigned

Returns:	the image object type will depend on the loader (ie. pygame surface)

parse_xml(node: xml.etree.ElementTree.Element)[source]¶

Parse an Object from ElementTree xml node

Parameters:	node – the node to be parsed

class pytmx.pytmx.TiledObjectGroup(parent, node)[source]¶

Bases: pytmx.pytmx.TiledElement, list

Represents a Tiled ObjectGroup

Supports any operation of a normal list.

parse_xml(node: xml.etree.ElementTree.Element)[source]¶

Parse an Object Group from ElementTree xml node

Parameters:	node – node to parse

class pytmx.pytmx.TiledImageLayer(parent, node)[source]¶

Bases: pytmx.pytmx.TiledElement

Represents Tiled Image Layer

The image associated with this layer will be loaded and assigned a GID.

image¶

Image for the object, if assigned

Returns:	the image object type will depend on the loader (ie. pygame surface)

parse_xml(node: xml.etree.ElementTree.Element)[source]¶: Parse an Image Layer from ElementTree xml node

class pytmx.pytmx.TileFlags(flipped_horizontally, flipped_vertically, flipped_diagonally)¶

Bases: tuple

flipped_diagonally¶: Alias for field number 2

flipped_horizontally¶: Alias for field number 0

flipped_vertically¶: Alias for field number 1

pytmx.pytmx.convert_to_bool(value: str) → bool[source]¶

Convert a few common variations of “true” and “false” to boolean

Parameters:	value – string to test
Raises:	`ValueError` – if value cannot be converted to a bool

pytmx.pytmx.parse_properties(node: xml.etree.ElementTree.Element) → Dict[KT, VT][source]¶

Parse a Tiled xml node and return a dict that represents a Tiled “property”

Parameters:	node – etree element to inspect
Returns:	dict of the properties, as set in the Tiled editor for the object

pytmx.util_pygame module¶

This file is part of pytmx.

pytmx is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

pytmx is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with pytmx. If not, see <http://www.gnu.org/licenses/>.

pytmx.util_pygame.load_pygame(filename: str, *args, **kwargs) → pytmx.pytmx.TiledMap[source]¶

Load a TMX file, images, and return a TiledMap class

PYGAME USERS: Use me.

this utility has ‘smart’ tile loading. by default any tile without transparent pixels will be loaded for quick blitting. if the tile has transparent pixels, then it will be loaded with per-pixel alpha. this is a per-tile, per-image check.

if a color key is specified as an argument, or in the tmx data, the per-pixel alpha will not be used at all. if the tileset’s image has colorkey transparency set in Tiled, the util_pygam will return images that have their transparency already set.

TL;DR: Don’t attempt to convert() or convert_alpha() the individual tiles. It is already done for you.

Parameters:	filename – filename to load
Returns:	new pytmx.TiledMap object

pytmx.util_pygame.pygame_image_loader(filename: str, colorkey: Union[Tuple[int, int, int, int], Tuple[int, int, int], int, str, None], **kwargs)[source]¶

pytmx image loader for pygame

Parameters:	filename – filename, including path, to load colorkey – colorkey for the image
Returns:	function to load tile images

pytmx.util_pygame.simplify(all_points: List[Union[Tuple[int, int], pygame.math.Vector2, pytmx.pytmx.Point]], tilewidth: int, tileheight: int) → List[pygame.Rect][source]¶

Given a list of points, return list of rects that represent them kludge:

“A kludge (or kluge) is a workaround, a quick-and-dirty solution, a clumsy or inelegant, yet effective, solution to a problem, typically using parts that are cobbled together.”

– wikipedia

turn a list of points into a rects adjacent rects will be combined.

plain english:

the input list must be a list of tuples that represent the areas to be combined into rects the rects will be blended together over solid groups

so if data is something like:

0 1 1 1 0 0 0 0 1 1 0 0 0 0 0 0 0 0 0 4 0 0 0 0 0 0 4 0 0 0 0 0 0 0 0 0 0 1 1 1 1 1

you’ll have the 4 rects that mask the area like this:

..######…… ..####…….. ……….##.. ……….##.. ………….. ….##########

pretty cool, right?

there may be cases where the number of rectangles is not as low as possible, but I haven’t found that it is excessively bad. certainly much better than making a list of rects, one for each tile on the map!

pytmx.util_pygame.build_rects(tmxmap: pytmx.pytmx.TiledMap, layer: Union[int, str], tileset: Union[str, int, None], real_gid: Optional[int]) → List[pygame.Rect][source]¶

Generate a set of non-overlapping rects that represents the distribution of the specified gid.

Useful for generating rects for use in collision detection

GID Note: You will need to add 1 to the GID reported by Tiled.

Parameters:	tmxmap – TiledMap object layer – int or string name of layer tileset – int or string name of tileset real_gid – Tiled GID of the tile + 1 (see note)
Returns:	list of pygame Rect objects

pytmx.util_pyglet module¶

This file is part of pytmx.

pytmx is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

pytmx is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with pytmx. If not, see <http://www.gnu.org/licenses/>.

pytmx.util_pyglet.load_pyglet(filename, *args, **kwargs)[source]¶

pytmx.util_pyglet.pyglet_image_loader(filename, colorkey, **kwargs)[source]¶

basic image loading with pyglet

returns pyglet Images, not textures

This is a basic proof-of-concept and is likely to fail in some situations.

Missing:: Transparency Tile Rotation

This is slow as well.

pytmx.util_pysdl2 module¶

Module contents¶

This file is part of pytmx.

pytmx is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

pytmx is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with pytmx. If not, see <http://www.gnu.org/licenses/>.