diff --git a/pytiled_parser/layer.py b/pytiled_parser/layer.py index a2cf80b..bf8ea49 100644 --- a/pytiled_parser/layer.py +++ b/pytiled_parser/layer.py @@ -1,9 +1,10 @@ -"""This module handles parsing all types of layers. +"""This module provides classes for all layer types -See: - - https://doc.mapeditor.org/en/stable/reference/json-map-format/#layer - - https://doc.mapeditor.org/en/stable/manual/layers/ - - https://doc.mapeditor.org/en/stable/manual/editing-tile-layers/ +There is the base Layer class, which TileLayer, ObjectLayer, ImageLayer, +and LayerGroup all derive from. The base Layer class is never directly used, +and serves only as an abstract base for common elements between all types. + +For more information about Layers, see [Tiled's Manual](https://doc.mapeditor.org/en/stable/manual/layers/) """ # pylint: disable=too-few-public-methods @@ -20,9 +21,12 @@ from pytiled_parser.tiled_object import TiledObject @attr.s(auto_attribs=True, kw_only=True) class Layer: - """Class that all layers inherit from. + """Base class that all layer types inherit from. Includes common attributes between + the various types of layers. - See: https://doc.mapeditor.org/en/stable/reference/json-map-format/#layer + [TMX Reference](https://doc.mapeditor.org/en/stable/reference/tmx-map-format/#layer) + + [JSON Reference](https://doc.mapeditor.org/en/stable/reference/json-map-format/#layer) Attributes: name: The name of the layer object. @@ -35,6 +39,7 @@ class Layer: size: Ordered pair of size of map in tiles. offset: Rendering offset of the layer object in pixels. properties: Properties for the layer. + tint_color: Tint color that is multiplied with any graphics in this layer. """ name: str @@ -56,9 +61,14 @@ TileLayerGrid = List[List[int]] @attr.s(auto_attribs=True) class Chunk: - """Chunk object for infinite maps. + """Chunk object for infinite maps. Stores `data` like you would have in a normal + TileLayer but only for the area specified by `coordinates` and `size`. - See: https://doc.mapeditor.org/en/stable/reference/json-map-format/#chunk + [Infinite Maps Docs](https://doc.mapeditor.org/en/stable/manual/using-infinite-maps/) + + [TMX Reference](https://doc.mapeditor.org/en/stable/reference/tmx-map-format/#chunk) + + [JSON Reference](https://doc.mapeditor.org/en/stable/reference/json-map-format/#chunk) Attributes: coordinates: Location of chunk in tiles. @@ -80,15 +90,18 @@ LayerData = Union[TileLayerGrid, List[Chunk]] @attr.s(auto_attribs=True, kw_only=True) class TileLayer(Layer): - """Tile map layer containing tiles. + """The base type of layer which stores tile data for an area of a map. - See: - https://doc.mapeditor.org/en/stable/reference/json-map-format/#tile-layer-example + [Tiled Docs](https://doc.mapeditor.org/en/stable/manual/layers/#tile-layers) + + [TMX Reference](https://doc.mapeditor.org/en/stable/reference/tmx-map-format/#layer) + + [JSON Reference](https://doc.mapeditor.org/en/stable/reference/json-map-format/#tile-layer-example) Attributes: - chunks: list of chunks (infinite maps) - data: Either an 2 dimensional array of integers representing the global tile - IDs for the map layer, or a list of chunks for an infinite map. + chunks: List of chunks (only populated for infinite maps) + data: A 2 dimensional array of integers representing the global tile + IDs for the map layer (only populated for non-infinite maps) """ chunks: Optional[List[Chunk]] = None @@ -97,13 +110,13 @@ class TileLayer(Layer): @attr.s(auto_attribs=True, kw_only=True) class ObjectLayer(Layer): - """TiledObject Group Object. + """A Layer type which stores a list of Tiled Objects - The object group is in fact a map layer, and is hence called "object layer" in - Tiled. + [Tiled Docs](https://doc.mapeditor.org/en/stable/manual/layers/#object-layers) - See: - https://doc.mapeditor.org/en/stable/reference/json-map-format/#object-layer-example + [TMX Reference](https://doc.mapeditor.org/en/stable/reference/tmx-map-format/#objectgroup) + + [JSON Reference](https://doc.mapeditor.org/en/stable/reference/json-map-format/#object-layer-example) Attributes: tiled_objects: List of tiled_objects in the layer. @@ -121,9 +134,13 @@ class ObjectLayer(Layer): @attr.s(auto_attribs=True, kw_only=True) class ImageLayer(Layer): - """Map layer containing images. + """Map layer containing a single image - See: https://doc.mapeditor.org/en/stable/manual/layers/#image-layers + [Tiled Docs](https://doc.mapeditor.org/en/stable/manual/layers/#image-layers) + + [TMX Reference](https://doc.mapeditor.org/en/stable/reference/tmx-map-format/#imagelayer) + + [JSON Reference](https://doc.mapeditor.org/en/stable/reference/json-map-format/#layer) Attributes: image: The image used by this layer. @@ -136,13 +153,17 @@ class ImageLayer(Layer): @attr.s(auto_attribs=True, kw_only=True) class LayerGroup(Layer): - """A layer that contains layers (potentially including other LayerGroups). + """A layer that contains layers (potentially including other LayerGroups, nested infinitely). - Offset and opacity recursively affect child layers. + In Tiled, offset and opacity recursively affect child layers, however that is not enforced during + parsing by pytiled_parser, and is up to the implementation how to handle recursive effects of + LayerGroups - See: - - https://doc.mapeditor.org/en/stable/reference/json-map-format/#layer - - https://doc.mapeditor.org/en/stable/manual/layers/#group-layers + [Tiled Docs](https://doc.mapeditor.org/en/stable/manual/layers/#group-layers) + + [TMX Reference](https://doc.mapeditor.org/en/stable/reference/tmx-map-format/#group) + + [JSON Reference](https://doc.mapeditor.org/en/stable/reference/json-map-format/#layer) Attributes: Layers: list of layers contained in the group. diff --git a/pytiled_parser/parser.py b/pytiled_parser/parser.py index 9a0a389..4dfbcc0 100644 --- a/pytiled_parser/parser.py +++ b/pytiled_parser/parser.py @@ -14,11 +14,11 @@ def parse_map(file: Path) -> TiledMap: file: Path to the map file Returns: - Tiledmap: a properly typed TiledMap + TiledMap: a properly typed TiledMap """ parser = check_format(file) - # The type ignores are because mypy for some reaosn thinks those functions return Any + # The type ignores are because mypy for some reason thinks those functions return Any if parser == "tmx": return tmx_map_parse(file) # type: ignore elif parser == "json": diff --git a/pytiled_parser/tileset.py b/pytiled_parser/tileset.py index edbb409..91e4221 100644 --- a/pytiled_parser/tileset.py +++ b/pytiled_parser/tileset.py @@ -1,3 +1,9 @@ +"""Provides an interface for Tilesets and the various objects within them. + +Also see [Tiled's Docs for Editing Tilesets](https://doc.mapeditor.org/en/stable/manual/editing-tilesets/) +and [TMX Reference](https://doc.mapeditor.org/en/stable/reference/tmx-map-format/#tileset) +and [JSON Reference](https://doc.mapeditor.org/en/stable/reference/json-map-format/#tileset) +""" # pylint: disable=too-few-public-methods from pathlib import Path from typing import Dict, List, NamedTuple, Optional @@ -11,12 +17,16 @@ from .wang_set import WangSet class Grid(NamedTuple): - """Contains info for isometric maps. + """Contains info used in isometric maps. This element is only used in case of isometric orientation, and determines how tile - overlays for terrain and collision information are rendered. + overlays for terrain and collision information are rendered. - Args: + [TMX Reference](https://doc.mapeditor.org/en/stable/reference/tmx-map-format/#tmx-grid) + + [JSON Reference](https://doc.mapeditor.org/en/stable/reference/json-map-format/#grid) + + Attributes: orientation: Orientation of the grid for the tiles in this tileset (orthogonal or isometric). width: Width of a grid cell. @@ -31,9 +41,15 @@ class Grid(NamedTuple): class Frame(NamedTuple): """Animation Frame object. - This is only used as a part of an animation for Tile objects. + This is only used as a part of an animation for Tile objects. A frame simply points + to a tile within the tileset, and gives a duration. Meaning that tile would be + displayed for the given duration. - Args: + [TMX Reference](https://doc.mapeditor.org/en/stable/reference/tmx-map-format/#tmx-frame) + + [JSON Reference](https://doc.mapeditor.org/en/stable/reference/json-map-format/#json-frame) + + Attributes: tile_id: The local ID of a tile within the parent tile set object. duration: How long in milliseconds this frame should be displayed before advancing to the next frame. @@ -48,35 +64,56 @@ class Transformations: """Transformations Object. This is used to store what transformations may be performed on Tiles - within a tileset. (This is primarily used with wang sets, however could - be used for any means a game wants really.) + within a tileset. Within Tiled this primarily used with wang sets and + the terrain system, however, could be used for any means a game/engine + wants to really. - Args: + [TMX Reference](https://doc.mapeditor.org/en/stable/reference/tmx-map-format/#transformations) + + [JSON Reference](https://doc.mapeditor.org/en/stable/reference/json-map-format/#transformations) + + Attributes: hflip: Allow horizontal flip? vflip: Allow vertical flip? rotate: Allow rotation? prefer_untransformed: Should untransformed tiles be preferred? """ - hflip: Optional[bool] = None - vflip: Optional[bool] = None - rotate: Optional[bool] = None - prefer_untransformed: Optional[bool] = None + hflip: bool = False + vflip: bool = False + rotate: bool = False + prefer_untransformed: bool = False @attr.s(auto_attribs=True, kw_only=True) class Tile: - # FIXME: args """Individual tile object. - See: https://doc.mapeditor.org/en/stable/reference/tmx-map-format/#tile + This class more closely resembles the JSON format than TMX. A number of values + within this class in the TMX format are pulled into other sub-tags such as . - Args: - id: The local tile ID within its tileset. - type: The type of the tile. Refers to an object type and is used by tile - objects. - terrain: Defines the terrain type of each corner of the tile. - animation: Each tile can have exactly one animation associated with it. + [TMX Reference](https://doc.mapeditor.org/en/stable/reference/tmx-map-format/#tile) + + [JSON Reference](https://doc.mapeditor.org/en/stable/reference/json-map-format/#tile-definition) + + Attributes: + id: The local tile ID within it's tileset. + opacity: The opacity this Tiled should be rendered with. + type: An optional, arbitrary string that can be used to denote different + types of tiles. For example "wall" or "floor". + animation: A list of [Frame][pytiled_parser.tileset.Frame] objects which + makeup the animation for an animated tile. + objects: An [ObjectLayer][pytiled_parser.layer.ObjectLayer] which contains + objects that can be used for custom collision on the Tile. This field + is set by the Tile Collision editor in Tiled. + image: A path to the image for this tile. + image_width: The width of this tile's image. + image_height: The height of this tile's image. + properties: A list of properties on this Tile. + tileset: The [Tileset][pytiled_parser.tileset.Tileset] this tile came from. + flipped_horizontally: Should this Tile be flipped horizontally? + flipped_diagonally: Should this Tile be flipped diagonally? + flipped_vertically: Should this Tile be flipped vertically? """ id: int @@ -96,28 +133,46 @@ class Tile: @attr.s(auto_attribs=True) class Tileset: - """Object for storing a TSX with all associated collision data. + """A Tileset is a collection of tiles. - Args: + As with the Tile class, this one more closely resembles the JSON format than TMX. + + [TMX Reference](https://doc.mapeditor.org/en/stable/reference/tmx-map-format/#tileset) + + [JSON Reference](https://doc.mapeditor.org/en/stable/reference/json-map-format/#tileset) + + Attributes: name: The name of this tileset. - max_tile_size: The maximum size of a tile in this tile set in pixels. - spacing: The spacing in pixels between the tiles in this tileset (applies to - the tileset image). - margin: The margin around the tiles in this tileset (applies to the tileset - image). + tile_width: The width of a tile in this tileset in pixels. + tile_height: The height of a tile in this tileset in pixels. tile_count: The number of tiles in this tileset. columns: The number of tile columns in the tileset. For image collection tilesets it is editable and is used when displaying the tileset. - grid: Only used in case of isometric orientation, and determines how tile - overlays for terrain and collision information are rendered. + spacing: The spacing in pixels between the tiles in this tileset (applies to + the tileset image). + firstgid: The global ID to give to the first Tile in this tileset. Global IDs + for the rest of the tiles will increment from this number. + type: Will always be `tileset`. Is statically included as a way to determine the + type of a JSON file since Tiled does not have different extesnsions for map + and tileset JSON files(as opposed to TMX/TSX files) + spacing: Spacing between adjacent tiles in the image in pixels. + margin: Buffer between the image edge and the first tile in the image in pixels. + image: Used for spritesheet tile sets. + image_width: The width of the `image` in pixels. + image_height: The height of the `image` in pixels. + transformations: What types of transformations are allowed on tiles within this + Tileset + background_color: The background color of the tileset. tileoffset: Used to specify an offset in pixels when drawing a tile from the tileset. When not present, no offset is applied. - image: Used for spritesheet tile sets. + transparent_color: A color that acts as transparent on any tiles within the + tileset. + grid: Only used in case of isometric orientation, and determines how tile + overlays for terrain and collision information are rendered. + properties: The properties for this Tileset. tiles: Dict of Tile objects by Tile.id. - tsx_file: Path of the file containing the tileset, None if loaded internally - from a map - parent_dir: Path of the parent directory of the file containing the tileset, - None if loaded internally from a map + wang_sets: List of WangSets used by the terrain system + alignment: Which alignment to use for tile objects from this tileset. """ name: str