pytmx package

Submodules

pytmx.pytmx module

Copyright (C) 2012-2023, 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 <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

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 (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)

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)

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)

Bases: pytmx.pytmx.TiledElement

Contains the layers, objects, and images from a Tiled .tmx map.

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

Add a layer to the map.

Parameters:layer (TiledLayer) – The layer.

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

Add a tileset to the map.

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

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

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

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

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

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)

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)

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

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

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

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)

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

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

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

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

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

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]

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

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

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

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 (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)

Bases: pytmx.pytmx.TiledElement

Represents any Tiled Object.

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

apply_transformations() → List[pytmx.pytmx.Point]

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

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)

Bases: pytmx.pytmx.TiledElement, list

Represents a Tiled ObjectGroup

Supports any operation of a normal list.

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

Parse an Object Group from ElementTree xml node

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

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

Parse a Tile Layer from ElementTree xml node.

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

tiles()

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

Bases: object

Contains custom Tiled types.

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: xml.etree.ElementTree.Element) → TiledTileset

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

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

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]

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

pytmx.util_pygame module

Copyright (C) 2012-2023, 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/>.

pytmx.util_pygame.load_pygame(filename: str, *args, **kwargs) → pytmx.pytmx.TiledMap

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)

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

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[int, str, None], real_gid: Optional[int]) → List[pygame.rect.Rect]

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

Copyright (C) 2012-2017, 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/>.

pytmx.util_pyglet.load_pyglet(filename, *args, **kwargs)

pytmx.util_pyglet.pyglet_image_loader(filename, colorkey, **kwargs)

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

Copyright (C) 2012-2023, 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/>.