Tiled Map Reader

class arcade.tilemap.TileMap(map_file: str | Path = '', scaling: float = 1.0, layer_options: Dict[str, Dict[str, Any]] | None = None, use_spatial_hash: bool = False, hit_box_algorithm: HitBoxAlgorithm | None = None, tiled_map: pytiled_parser.TiledMap | None = None, offset: Vec2 = Vec2(0, 0), texture_atlas: 'TextureAtlas' | None = None, lazy: bool = False)

Bases:

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 – Global scaling to apply to all Sprites.

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

• use_spatial_hash – 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 – The hit box algorithm to use for the Sprite’s in this layer.

• tiled_map – 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 – 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.

• texture_atlas – A default texture atlas to use for the SpriteLists created by this map. If not supplied the global default atlas will be used.

• lazy – SpriteLists will be created lazily.

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 - The hit box algorithm to use for the Sprite’s in this layer. 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 texture_atlas - A texture atlas to use for the SpriteList from this layer, if none is supplied then the one defined at the map level will be used.

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.

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

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 – The X Coordinate to convert

• y – The Y Coordinate to convert

get_tilemap_layer(layer_path: str) → Layer | None

background_color: Color | None

The background color of the map.

height: float

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

object_lists: Dict[str, List[TiledObject]]

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

offset: Vec2

A tuple containing the X and Y position offset values.

scaling: float

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

sprite_lists: Dict[str, SpriteList]

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

tile_height: float

The height in pixels of each tile.

tile_width: float

The width in pixels of each tile.

tiled_map: TiledMap

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: float

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

arcade.tilemap.load_tilemap(map_file: str | Path, scaling: float = 1.0, layer_options: Dict[str, Dict[str, Any]] | None = None, use_spatial_hash: bool = False, hit_box_algorithm: HitBoxAlgorithm | None = None, offset: Vec2 = Vec2(0, 0), texture_atlas: 'TextureAtlas' | None = None, lazy: bool = False) → TileMap

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 – The global scaling to apply to all Sprite’s within the map.

• use_spatial_hash – 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 – The hit box algorithm to use for collision detection.

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

• offset – 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.

• lazy – SpriteLists will be created lazily.

arcade.tilemap.read_tmx(map_file: str | Path) → TiledMap

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

Exists to provide info for outdated code bases.