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 <https://www.gnu.org/licenses/>.

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

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 (str) – String containing xml data.
Returns:	The TiledElement from the xml string.
Return type:	TiledElement

class pytmx.pytmx.TiledImageLayer(parent, node: xml.etree.ElementTree.Element)[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).
Return type:	???

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

class pytmx.pytmx.TiledMap(filename: Optional[str] = None, custom_property_filename: Optional[List[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.

add_layer(layer: Union[TiledTileLayer, TiledImageLayer, TiledGroupLayer, TiledObjectGroup]) → None[source]¶

Add a layer to the map.

Parameters:	layer (TiledLayer) – The layer.

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

get_layer_by_name(name: str) → Union[TiledTileLayer, TiledImageLayer, TiledGroupLayer, TiledObjectGroup][source]¶

Return a layer by name.

Parameters:	name (str) – The layer’s name. Case-sensitive!
Returns:	The layer.
Return type:	TiledLayer
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 (int) – ID of the object, from Tiled.
Returns:	The found object.
Return type:	TiledObject

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

Find an object by name, case-sensitive.

Parameters:	name (str) – The object’s name.
Returns:	The found object.
Return type:	TiledObject

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

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

Returns:	The tile colliders.
Return type:	Iterable[Tuple[int, List[Dict]]]

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

Return the tile image GID for this location.

Parameters:	x (int) – The x coordinate. y (int) – The y coordinate. layer (int) – The layer’s number.
Returns:	The image object type will depend on the loader (ie. pygame.Surface).
Return type:	???
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 (int) – The x coordinate. y (int) – The y coordinate. layer (int) – The layer’s number.
Returns:	the image object type will depend on the loader (ie. pygame surface).
Return type:	???
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 (int) – GID of image.
Returns:	The image object type will depend on the loader (ie. pygame.Surface).
Return type:	???
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.

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

Parameters:	gid (int) – GID to be searched for.
Returns:	(int, int, int) tuples, where the layer is index of the visible tile layers.
Return type:	Iterable[MapPoint]

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

Return the tile image GID for this location.

Parameters:	x (int) – The x coordinate. y (int) – The y coordinate. layer (int) – The layer number.
Returns:	Dictionary of the properties for tile in this location or None.
Return type:	Optional[dict]
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 (int) – GID.
Returns:	Dictionary of properties for GID, or None.
Return type:	Optional[dict]

get_tile_properties_by_layer(layer: int)[source]¶

Get the tile properties of each GID in layer.

Parameters:	layer (int) – The layer number.
Returns:	???
Return type:	???

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 (int) – GID of tile image.
Returns:	The tileset that owns the GID.
Return type:	TiledTileset
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 (int) – GID. that is found in the .tmx file data.
Returns:	???
Return type:	Optional[List[int]]

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

objectgroups¶

Returns iterator of all object groups.

Returns:	???.
Return type:	Iterable[TiledObjectGroup]

objects¶

Returns iterator of all the objects associated with the map.

Returns:	All objects associated with the map.
Return type:	Iterable[TiledObject]

parse_json(data: dict) → None[source]¶

Parse custom data types from a JSON object

Parameters:	data (dict) – Dictionary from JSON object to parse

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

Parse a map from ElementTree xml node.

Parameters:	node (ElementTree.Element) – ElementTree xml node to parse.

pixels_to_tile_pos(position: Tuple[int, int]) → Tuple[int, int][source]¶

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

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

Parameters:	tiled_gid (int) – GID that is found in TMX data. flags – TileFlags.
Returns:	New or existing GID for pytmx use.
Return type:	int

register_gid_check_flags(tiled_gid: int) → int[source]¶

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

Checks the GID for rotation/flip flags

Parameters:	tiled_gid (int) – GID that is found in TMX data.
Returns:	New or existing GID for pytmx use.
Return type:	int

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 (int) – GID. properties (dict) – Python dictionary of properties for GID.

visible_layers¶

Returns iterator of Layer objects that are set “visible”.

Returns:	Iterator of Layer objects that are set “visible”.
Return type:	???

visible_object_groups¶

Return iterator of object group indexes that are set “visible”.

Returns:	A list of object group indexes that are set to “visible”.
Return type:	Iterable[TiledObjectGroup]

visible_tile_layers¶

Return iterator of layer indexes that are set “visible”.

Returns:	A list of layer indexes.
Return type:	Iterable[TiledTileLayer]

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

Bases: pytmx.pytmx.TiledElement

Represents any Tiled Object.

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

apply_transformations() → List[pytmx.pytmx.Point][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).
Return type:	???

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

Parse an Object from ElementTree xml node.

Parameters:	node (ElementTree.Element) – The node to be parsed.
Returns:	The parsed xml node.
Return type:	TiledObject

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

Bases: pytmx.pytmx.TiledElement, list

Represents a Tiled ObjectGroup

Supports any operation of a normal list.

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

Parse an Object Group from ElementTree xml node

Parameters:	node (ElementTree.Element) – 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.
Return type:	Iterable[Tuple[int, int, int]]

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

Parse a Tile Layer from ElementTree xml node.

Parameters:	node (ElementTree.Element) – Node to parse.
Returns:	The parsed tile layer.
Return type:	TiledTileLayer

tiles()[source]¶

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

Yields:	??? – Iterator of X, Y, Image tuples for each tile in the layer

class pytmx.pytmx.TiledClassType(name: str, members: List[dict])[source]¶

Bases: object

Contains custom Tiled types.

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: xml.etree.ElementTree.Element) → TiledTileset[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 (ElementTree.Element) – Node to parse.
Returns:
Return type:	TiledTileset

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

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

Parameters:	value (str) – String to test.
Raises:	`ValueError` – If value cannot be converted to a boolean.
Returns:	The converted boolean.
Return type:	bool

pytmx.pytmx.resolve_to_class(value: str, custom_types: dict) → pytmx.pytmx.TiledClassType[source]¶

Converts tiled custom types to a python class.

Parameters:	value (str) – name of the class. custom_types (dict) – A dictionary with the custom types created by users.
Raises:	`ValueError` – if value cannot be converted to a class.
Returns:	The converted python class type.
Return type:	TiledClassType

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

Parse a Tiled xml node and return a dict.

Parameters:	node (ElementTree.Element) – Etree element to inspect.
Returns:	Dictionary of the properties, as set in the Tiled editor.
Return type:	Dict