# cocos.tiles module

Tile map management and rendering.

This module provides an API for loading, saving and rendering a map constructed of image tiles.

exception `ResourceError`

  Bases: `Exception`

exception `TilesPropertyWithoutName`

  Bases: `Exception`

exception `TilesPropertyWithoutValue`

  Bases: `Exception`

exception `TmxUnsupportedVariant`

  Bases: `Exception`

class `Cell`(i, j, width, height, properties, tile)

  Bases: `object`

  Base class for cells from rect and hex maps.

  Common attributes:

      i, j            -- index of this cell in the map
      position        -- the above as a tuple
      width, height   -- dimensions
      properties      -- arbitrary properties
      cell            -- cell from the MapLayer's cells

  Properties are available through the dictionary interface, ie. if the cell has a property ‘cost’ then you may access it as:

  > cell[‘cost’]

  You may also set properties in this way and use the .get() method to supply a default value.

  If the named property does not exist on the cell it will be looked up on the cell’s tile.

  `get`(key, default=None)
  property `position`

class `HexCell`(i, j, ignored, height, properties, tile)

  Bases: `cocos.tiles.Cell`

  A flat-top, regular hexagon cell from a HexMap.

  Cell attributes:

      i, j            -- index of this cell in the map
      width, height   -- dimensions
      properties      -- arbitrary properties
      cell            -- cell from the MapLayer's cells

  Read-only attributes:

      x, y            -- bottom-left pixel
      top             -- y pixel extent
      bottom          -- y pixel extent
      left            -- (x, y) of left corner pixel
      right           -- (x, y) of right corner pixel
      center          -- (x, y)
      origin          -- (x, y) of bottom-left corner of bounding rect
      topleft         -- (x, y) of top-left corner pixel
      topright        -- (x, y) of top-right corner pixel
      bottomleft      -- (x, y) of bottom-left corner pixel
      bottomright     -- (x, y) of bottom-right corner pixel
      midtop          -- (x, y) of middle of top side pixel
      midbottom       -- (x, y) of middle of bottom side pixel
      midtopleft      -- (x, y) of middle of left side pixel
      midtopright     -- (x, y) of middle of right side pixel
      midbottomleft   -- (x, y) of middle of left side pixel
      midbottomright  -- (x, y) of middle of right side pixel

  Note that all pixel attributes are not adjusted for screen, view or layer transformations.

  `get_bottom`()
  `get_bottomleft`()
  `get_bottomright`()
  `get_center`()
  `get_left`()
  `get_midbottom`()
  `get_midbottomleft`()
  `get_midbottomright`()
  `get_midtop`()
  `get_midtopleft`()
  `get_midtopright`()
  `get_origin`()
  `get_right`()
  `get_top`()
  `get_topleft`()
  `get_topright`()
  property `bottom`
  property `bottomleft`
  property `bottomright`
  property `center`
  property `left`
  property `midbottom`
  property `midbottomleft`
  property `midbottomright`
  property `midtop`
  property `midtopleft`
  property `midtopright`
  property `origin`
  property `right`
  property `top`
  property `topleft`
  property `topright`

class `HexMap`(id, th, cells, origin=None, properties=None)

  Bases: `cocos.tiles.RegularTesselationMap`

  MapLayer with flat-top, regular hexagonal cells.

  Calculated attributes:

      edge_length -- length of an edge in pixels = int(th / sqrt(3))
      tw          -- with of a "tile" in pixels = edge_length * 2

  Hexmaps store their cells in an offset array, column-major with y increasing up, such that a map:

        /d\ /h\          .
      /b\_/f\_/          .
      \_/c\_/g\          .
      /a\_/e\_/          .
      \_/ \_/            .

  has cells = [[‘a’, ‘b’], [‘c’, ‘d’], [‘e’, ‘f’], [‘g’, ‘h’]]

  (and this the cell at (0, 0) is ‘a’ and (1, 1) is ‘d’)

  `get_at_pixel`(x, y)

    Get the Cell at pixel (x,y).

    Return None if out of bounds.

  `get_in_region`(left, bottom, right, top)

    Return cells (in [column][row]) that are within the pixel bounds specified by the bottom-left (left, bottom) and top-right (right, top) corners.

  `get_key_at_pixel`(x, y)

    returns the grid coordinates for the hex that covers the point (x, y)

    Reference:

      Hexagonal grid math, by Ruslan Shestopalyuk http://blog.ruslans.com/2011/02/hexagonal-grid-math.html

  `get_neighbor`(cell, direction)

    Get the neighbor HexCell in the given direction which is one of self.UP, self.DOWN, self.UP_LEFT, self.UP_RIGHT, self.DOWN_LEFT or self.DOWN_RIGHT.

    Return None if out of bounds.

  `get_neighbors`(cell)

    Get all neighbor cells for the nominated cell.

    Return a dict with the directions (self.UP, self.DOWN, etc) as keys and neighbor cells as values.

  `DOWN` = 'down'
  `DOWN_LEFT` = 'down left'
  `DOWN_RIGHT` = 'down right'
  `UP` = 'up'
  `UP_LEFT` = 'up left'
  `UP_RIGHT` = 'up right'

class `HexMapLayer`(id, ignored, th, cells, origin=None, properties=None)

  Bases: `cocos.tiles.HexMap`, `cocos.tiles.MapLayer`

  A renderable, scrollable tile map covered by hexagonal tiles

  While visually the tiles look hexagonal, the texture that draws each tile is rectangular and should comply:

  > - depicts an hexagon with upper and lower sides paralel to the x-axis

  > - area out of the hexagon should be transparent

  > - tile size must comply width == int(height / sqrt(3) * 2)

  Be warned that some hexagonal tilesets found in the net use other proportions or the pointy orientation ( left and right sides paralel to the y-axis) ; neither will work with HexMapLayer

  The Layer has a calculated attribute:

      edge_length -- length of an edge in pixels = int(th / sqrt(3))
      tw          -- with of a "tile" in pixels = edge_length * 2

  Hexmaps store their cells in an offset array, column-major with y increasing up, such that a map:

        /d\ /h\        .
      /b\_/f\_/        .
      \_/c\_/g\        .
      /a\_/e\_/        .
      \_/ \_/          .

  has cells = [[‘a’, ‘b’], [‘c’, ‘d’], [‘e’, ‘f’], [‘g’, ‘h’]]

class `MapLayer`(properties)

  Bases: `cocos.layer.scrolling.ScrollableLayer`

  Base class for Maps.

  Maps are comprised of tiles and can figure out which tiles are required to be rendered on screen.

  Both rect and hex maps have the following attributes:

      id              -- identifies the map in XML and Resources
      (width, height) -- size of map in cells
      (px_width, px_height)      -- size of map in pixels
      (tw, th)        -- size of each cell in pixels
      (origin_x, origin_y, origin_z)  -- offset of map top left from origin in pixels
      cells           -- array [i][j] of Cell instances
      debug           -- display debugging information on cells
      properties      -- arbitrary properties

  The debug flag turns on textual display of data about each visible cell including its cell index, origin pixel and any properties set on the cell.

  `find_cells`(**requirements)

    Find all cells that match the properties specified.

    For example:

    > map.find_cells(player_start=True)

    Return a list of Cell instances.

  `get`(key, default=None)

    Gets a child given its name.

    Parameters

      name (str) – name of the reference to retrieve.

    Returns

      CocosNode – The child named ‘name’. Will raise an `Exception` if not present.

    Warning

    If a node is added with name, then removing it differently than by name will prevent the name to be recycled: attempting to add another node with this name will produce an Exception.

  `get_visible_cells`()

    Given the current view in map-space pixels, transform it based on the current screen-space transform and figure the region of map-space pixels currently visible.

    Pass to get_in_region to return a list of Cell instances.

  `is_visible`(rect)

    Determine whether the indicated rect (with .x, .y, .width and .height attributes) located in this Layer is visible.

  `set_cell_color`(i, j, color)
  `set_cell_opacity`(i, j, opacity)
  `set_debug`(debug)
  `set_dirty`()

    The viewport has changed in some way.

  `set_view`(x, y, w, h, viewport_x=0, viewport_y=0)

    Sets the position of the viewport for this layer.

    Parameters

      - x (float) – The view x position

      - y (float) – The view y position

      - w (float) – The width of the view

      - h (float) – The height of the view

      - viewport_ox (float) – The viewport x origin

      - viewport_oy (float) – The viewport y origin

  `debug` = False

class `RectCell`(i, j, width, height, properties, tile)

  Bases: `cocos.rect.Rect`, `cocos.tiles.Cell`

  A rectangular cell from a MapLayer.

  Cell attributes:

      i, j            -- index of this cell in the map
      x, y            -- bottom-left pixel
      width, height   -- dimensions
      properties      -- arbitrary properties
      cell            -- cell from the MapLayer's cells

  The cell may have the standard properties “top”, “left”, “bottom” and “right” which are booleans indicating that those sides are impassable. These are used by RectCellCollider.

  Note that all pixel attributes are not adjusted for screen, view or layer transformations.

  property `bottom`
  property `bottomleft`
  property `bottomright`
  property `center`
  property `left`
  property `midbottom`
  property `midleft`
  property `midright`
  property `midtop`
  property `origin`
  property `right`
  property `top`
  property `topleft`
  property `topright`

class `RectMap`(id, tw, th, cells, origin=None, properties=None)

  Bases: `cocos.tiles.RegularTesselationMap`

  Rectangular map.

  Cells are stored in column-major order with y increasing up, allowing [i][j] addressing:

      +---+---+---+
      | d | e | f |
      +---+---+---+
      | a | b | c |
      +---+---+---+

  Thus cells = [[‘a’, ‘d’], [‘b’, ‘e’], [‘c’, ‘f’]]

  (and thus the cell at (0, 0) is ‘a’ and (0, 1) is ‘d’)

  `get_at_pixel`(x, y)

    Return Cell at pixel px=(x,y) on the map.

    The pixel coordinate passed in is in the map’s coordinate space, unmodified by screen, layer or view transformations.

    Return None if out of bounds.

  `get_in_region`(left, bottom, right, top)

    Return cells that intersects the rectangle left, bottom, right, top in an area greater than zero

    (left, bottom) and (right, top) are the lower left and upper right corners respectively, in map’s coordinate space, unmodified by screen, layer or view transformations

    Return a list of Cell instances.

    When the rectangle has area zero results are a bit inconsistent:

      A rectangle which is a point intersects no cell A rectangle which is a segment and overlaps the cell boundaries intersects no cells A rectangle which is a segment and don’t overlaps the cell boundaries intersects some cells: the ones that the open segment intersects

  `get_key_at_pixel`(x, y)

    returns the grid coordinates for the hex that covers the point (x, y)

  `get_neighbor`(cell, direction)

    Get the neighbor Cell in the given direction (dx, dy) which is one of self.UP, self.DOWN, self.LEFT or self.RIGHT.

    Returns None if out of bounds.

  `get_neighbors`(cell, diagonals=False)

    Get all cells touching the sides of the nominated cell.

    If “diagonals” is True then return the cells touching the corners of this cell too.

    Return a dict with the directions (self.UP, self.DOWN, etc) as keys and neighbor cells as values.

  `DOWN` = (0, -1)
  `LEFT` = (-1, 0)
  `RIGHT` = (1, 0)
  `UP` = (0, 1)

class `RectMapCollider`

  Bases: `object`

  moved to cocos.mapcolliders

class `RectMapLayer`(id, tw, th, cells, origin=None, properties=None)

  Bases: `cocos.tiles.RectMap`, `cocos.tiles.MapLayer`

  A renderable, scrollable rect map.

class `RegularTesselationMap`

  Bases: `object`

  A regularly tesselated map that allows access to its cells by index (i, j).

  `get_cell`(i, j)

    Return Cell at cell pos=(i, j).

    Return None if out of bounds.

class `Resource`(filename)

  Bases: `object`

  Load some tile mapping resources from an XML file.

  `add_resource`(id, resource)
  `find`(cls)

    Find all elements of the given class in this resource.

  `find_file`(filename)
  `findall`(cls, ns='')

    Find all elements of the given class in this resource and all <requires>’ed resources.

  `get_resource`(ref)
  `handle`(tag)
  classmethod `register_factory`(name)
  `requires_factory`(tag)
  `resource_factory`(tag)
  `save_xml`(filename)

    Save this resource’s XML to the indicated file.

  `cache` = {}
  `factories` = {'hexmap': <function hexmap_factory>, 'image': <function image_factory>, 'imageatlas': <function imageatlas_factory>, 'rectmap': <function rectmap_factory>, 'requires': <function Resource.requires_factory>, 'resource': <function Resource.resource_factory>, 'tileset': <function tileset_factory>}

class `Tile`(id, properties, image, offset=None)

  Bases: `object`

  Tiles hold an image and some optional properties.

class `TileSet`(id, properties)

  Bases: `dict`

  Contains a set of Tile objects referenced by some id.

  `add`(properties, image, id=None)

    Add a new Tile to this TileSet, generating a unique id if necessary.

    Returns the Tile instance.

  classmethod `from_atlas`(name, firstgid, file, tile_width, tile_height, row_padding=0, column_padding=0)
  classmethod `generate_id`()
  `tile_id` = 0

class `TmxObject`(tmxtype, usertype, x, y, width=0, height=0, name=None, gid=None, tile=None, visible=1, points=None)

  Bases: `cocos.rect.Rect`

  Represents an object in a TMX object layer.

  Instances of this class are ussually constructed by calling TmxObject.fromxml

  Theres no validation of data pased to __init__:

      tmxtype: one of 'ellipse', 'polygon', 'polyline', 'rect', 'tile'
      name: An arbitrary string. The object's 'name' field in Tiled Editor.
      usertype: An arbitrary string. The object's 'type' field in Tiled Editor.
      x: The x coordinate of the bottomleft object's Axis Aligned Bounding Box.
      y: The y coordinate of the bottomleft object's Axis Aligned Bounding Box.
      width: The width of the object in pixels (defaults to 0).
      height: The height of the object in pixels (defaults to 0).
      gid: An reference to a tile (optional).
      visible: Whether the object is shown (1) or hidden (0). Defaults to 1.
      points: a sequence of coords (x, y) relative to bottomleft  thas enumerates
      the vertices in a 'polygon' or 'polyline'.

  A ‘rect’ AABB is itself, so x,y is it’s bottomleft corner.

  classmethod `fromxml`(tag, tilesets, map_height)
    Parameters
      tag xml tag

        assumed an object tag

      tileset enumerable giving tilesets

        only the tilesets used used by an object tile are needed, can be []

      map_height int

        map height in pixels, needed to change coords from tmx to gl

    Returns

      a TmxObject instance attributes in the instance will store the info parsed from the class

  `get`(key, default=None)

class `TmxObjectLayer`(name, color, objects, opacity=1, visible=1, position=(0, 0))

  Bases: `cocos.tiles.MapLayer`

  A layer composed of basic primitive shapes.

  Actually encompasses a TMX <objectgroup> but even the TMX documentation refers to them as object layers, so I will.

  TmxObjectLayers have some basic properties:

      position - ignored (cannot be edited in the current Tiled editor)
      name - the name of the object group.
      color - the color used to display the objects in this group.
      opacity - the opacity of the layer as a value from 0 to 1.
      visible - whether the layer is shown (1) or hidden (0).
      objects - the objects in this Layer (TmxObject instances)

  `collide`(rect, propname)

    Find all objects the rect is touching that have the indicated property name set.

  `find_cells`(**requirements)

    Find all objects with the given properties set.

    Called “find_cells” for compatibility with existing cocos tile API.

  classmethod `fromxml`(tag, tilesets, map_height)
  `get_at`(x, y)

    Return the first object found at the nominated (x, y) coordinate.

    Return an TmxObject instance or None.

  `get_in_region`(left, bottom, right, top)

    Return objects that overlaps any interior point of the rect with bottom-left (left, bottom) and top-right (right, top) corners.

    Return a list of TmxObject instances.

  `match`(**properties)

    Find all objects with the given properties set to the given values.

  `update`(dt, *args)

`color4_to_text`(v)

`decode_base64`(s)

  returns a bytes object

`decompress_gzip`(in_bytes)

  decompress the input array of bytes to an array of bytes using gzip

`decompress_zlib`(in_bytes)

  decompress the input array of bytes to an array of bytes using zlib

`hex_width`(height)

  Determine a regular hexagon’s width given its height.

`hexmap_factory`(resource, tag)

`image_factory`(resource, tag)

`imageatlas_factory`(resource, tag)

`load`(filename)

  Load resource(s) defined in the indicated XML file.

`load_tiles`(filename)

  Load some tile mapping resources from an XML file.

`load_tmx`(filename)

  Load some tile mapping resources from a TMX file.

`parse_tmx_points`(tag, obj_x, obj_y)

  parses tmx tag points into left, bottom, right, top, points

  Parameters
    tag xml tag

      assumed an object tag

    obj_x :

      object x position in gl coordinates

    obj_y :

      object y position in gl coordinates

  Returns

    tuple (left, bottom, width, height, points) left: leftmost x-position in points, gl coordinates system bottom: bottommost y-position in points, gl coordinates system width: width of point’s enclosing box height: height of point’s enclosing box points: list of points in a gl coordinates system relative to (left, bottom)

`rectmap_factory`(resource, tag)

`text_to_4tuple_int`(s)

`tileset_factory`(resource, tag)

`tmx_coords_to_gl`(x, y, map_height)