pytmx.pytmx module

Copyright (C) 2012-2021, Leif Theden <leif.theden@gmail.com>

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

Bases: object

Base class for all pytmx types

allow_duplicate_names = False

classmethod from_xml_string(xml_string: str) → pytmx.pytmx.TiledElement

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)

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

Add a layer to the map

add_tileset(tileset: pytmx.pytmx.TiledTileset) → None

Add a tileset to the map

get_layer_by_name(name: str)

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

Find an object by the object id

Parameters:obj_id – ID of the object, from Tiled

get_object_by_name(name) → pytmx.pytmx.TiledObject

Find an object by name, case-sensitive

Parameters:name – name of object

get_tile_colliders() → Iterable[Tuple[int, List[Dict[KT, VT]]]]

Return iterator of (gid, dict) pairs of tiles with colliders

get_tile_gid(x: int, y: int, layer: int) → int

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)

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)

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

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

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

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)

Get the tile properties of each GID in layer

Parameters:layer – layer number

get_tileset_from_gid(gid: int) → pytmx.pytmx.TiledTileset

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

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

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)

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

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

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

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)

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)

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)

Bases: pytmx.pytmx.TiledElement

Represents a TileLayer

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

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

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)

Parse a Tile Layer from ElementTree xml node

Parameters:node – node to parse

tiles()

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)

Bases: pytmx.pytmx.TiledElement

Represents a any Tiled Object

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

apply_transformations()

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)

Parse an Object from ElementTree xml node

Parameters:node – the node to be parsed

class pytmx.pytmx.TiledObjectGroup(parent, node)

Bases: pytmx.pytmx.TiledElement, list

Represents a Tiled ObjectGroup

Supports any operation of a normal list.

parse_xml(node: xml.etree.ElementTree.Element)

Parse an Object Group from ElementTree xml node

Parameters:node – node to parse

class pytmx.pytmx.TiledImageLayer(parent, node)

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)

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

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]

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