Tiled Map Reader

arcade.tilemap.TileMap

class arcade.tilemap.TileMap(map_file: Union[str, pathlib.Path] = '', scaling: float = 1.0, layer_options: Optional[Dict[str, Dict[str, Any]]] = None, use_spatial_hash: Optional[bool] = None, hit_box_algorithm: str = 'Simple', hit_box_detail: float = 4.5, tiled_map: Optional[pytiled_parser.tiled_map.TiledMap] = None, offset: pyglet.math.Vec2 = Vec2(0, 0))[source]

Class that represents a fully parsed and loaded map from Tiled. For examples on how to use this class, see: https://api.arcade.academy/en/latest/examples/platform_tutorial/step_09.html

Parameters
  • map_file (Union[str, Path]) – A JSON map file for a Tiled map to initialize from

  • scaling (float) – Global scaling to apply to all Sprites.

  • layer_options (Dict[str, Dict[str, Any]]) – Extra parameters for each layer.

  • use_spatial_hash (Optional[bool]) – If set to True, this will make moving a sprite in the SpriteList slower, but it will speed up collision detection with items in the SpriteList. Great for doing collision detection with static walls/platforms.

  • hit_box_algorithm (str) – One of ‘None’, ‘Simple’ or ‘Detailed’.

  • hit_box_detail (float) – Float, defaults to 4.5. Used with ‘Detailed’ to hit box.

  • tiled_map (pytiled_parser.TiledMap) – An already parsed pytiled-parser map object. Passing this means that the map_file argument will be ignored, and the pre-parsed map will instead be used. This can be helpful for working with Tiled World files.

  • offset (pyglet.math.Vec2) – Can be used to offset the position of all sprites and objects within the map. This will be applied in addition to any offsets from Tiled. This value can be overridden with the layer_options dict.

The layer_options parameter can be used to specify per layer arguments.

The available options for this are:

use_spatial_hash - A boolean to enable spatial hashing on this layer’s SpriteList. scaling - A float providing layer specific Sprite scaling. hit_box_algorithm - A string for the hit box algorithm to use for the Sprite’s in this layer. hit_box_detail - A float specifying the level of detail for each Sprite’s hitbox offset - A tuple containing X and Y position offsets for the layer custom_class - All objects in the layer are created from this class instead of Sprite. Must be subclass of Sprite. custom_class_args - Custom arguments, passed into the constructor of the custom_class

For example:

code-block:

layer_options = {
    "Platforms": {
        "use_spatial_hash": True,
        "scaling": 2.5,
        "offset": (-128, 64),
        "custom_class": Platform,
        "custom_class_args": {
            "health": 100
        }
    },
}

The keys and their values in each layer are passed to the layer processing functions using the ** operator on the dictionary.

Attributes:
tiled_map

The pytiled-parser map object. This can be useful for implementing features that aren’t supported by this class by accessing the raw map data directly.

width

The width of the map in tiles. This is the number of tiles, not pixels.

height

The height of the map in tiles. This is the number of tiles, not pixels.

tile_width

The width in pixels of each tile.

tile_height

The height in pixels of each tile.

background_color

The background color of the map.

scaling

A global scaling value to be applied to all Sprites in the map.

sprite_lists

A dictionary mapping SpriteLists to their layer names. This is used for all tile layers of the map.

object_lists

A dictionary mapping TiledObjects to their layer names. This is used for all object layers of the map.

offset

A tuple containing the X and Y position offset values.

get_cartesian(x: float, y: float) Tuple[float, float][source]

Given a set of coordinates in pixel units, this returns the cartesian coordinates.

This assumes the supplied coordinates are pixel coordinates, and bases the cartesian grid off of the Map’s tile size.

If you have a map with 128x128 pixel Tiles, and you supply coordinates 500, 250 to this function you’ll receive back 3, 2

Parameters
  • x (float) – The X Coordinate to convert

  • y (float) – The Y Coordinate to convert

arcade.tilemap.load_tilemap

arcade.tilemap.load_tilemap(map_file: Union[str, pathlib.Path], scaling: float = 1.0, layer_options: Optional[Dict[str, Dict[str, Any]]] = None, use_spatial_hash: Optional[bool] = None, hit_box_algorithm: str = 'Simple', hit_box_detail: float = 4.5, offset: pyglet.math.Vec2 = Vec2(0, 0)) arcade.tilemap.tilemap.TileMap[source]

Given a .json map file, loads in and returns a TileMap object.

A TileMap can be created directly using the classes __init__ function. This function exists for ease of use.

For more clarification on the layer_options key, see the __init__ function of the TileMap class

Parameters
  • map_file (Union[str, Path]) – The JSON map file.

  • scaling (float) – The global scaling to apply to all Sprite’s within the map.

  • use_spatial_hash (Optional[bool]) – If set to True, this will make moving a sprite in the SpriteList slower, but it will speed up collision detection with items in the SpriteList. Great for doing collision detection with static walls/platforms.

  • hit_box_algorithm (str) – One of ‘None’, ‘Simple’ or ‘Detailed’.

  • hit_box_detail (float) – Float, defaults to 4.5. Used with ‘Detailed’ to hit box.

  • layer_options (Dict[str, Dict[str, Any]]) – Layer specific options for the map.

  • offset (pyglet.math.Vec2) – Can be used to offset the position of all sprites and objects within the map. This will be applied in addition to any offsets from Tiled. This value can be overridden with the layer_options dict.

arcade.tilemap.read_tmx

arcade.tilemap.read_tmx(map_file: Union[str, pathlib.Path]) pytiled_parser.tiled_map.TiledMap[source]

Deprecated function to raise a warning that it has been removed.

Exists to provide info for outdated code bases.