Tile Maps

The RectMapLayer class extends the regular Cocos layer to handle a regular grid of tile images, or Cells. The map layer may be manipulated like any other Cocos layer. It also provides methods for interrogating the map contents to find cells (eg. under the mouse) or neighboring cells (up, down, left, right.)

Maps may be defined in Python code, but it is a little easier to do so in XML. To support map editing the maps support round-tripping to XML.

The XML File Specification

Assuming the following XML file called "example.xml":

<?xml version="1.0"?>
<resource>
  <require file="ground-tiles.xml" namespace="ground" />

  <rectmap id="level1">
   <column>
    <cell>
      <tile ref="ground:grass" />
    </cell>
    <cell>
      <tile ref="ground:house" />
      <property type="bool" name="secretobjective" value="True" />
    </cell>
   </column>
  </map>
</resource>

You may load that resource and examine it:

>>> r = load('example.xml')
>>> r['level1']

and then, assuming that level1 is a map:

>>> scene = cocos.scene.Scene(r['level1'])

if you wish for the level to scroll, you use the ScrollingManager:

>>> manager = tiles.ScrollingManager()
>>> manager.append(r['level1']

and later set the focus with:

>>> manager.set_focus(focus_x, focus_y)

Typically the focus is set to the center of the player's sprite. The focusing will honor any tile map boundaries and prevent area outside those boundaries from being displayed.

If you are only scrolling layers with sprites in them (ie. regular Cocos Layers, not RectMapLayers) then there are no boundaries and the map will scroll without bound in any direction.

If you wish you may force the focus to display areas outside your tile maps you may use the force_focus method of ScrollingManager.

XML file contents

XML resource files must contain a document-level tag <resource>:

<?xml version="1.0"?>
<resource>
 ...
</resource>

You may draw in other resource files by using the <require> tag:

<require file="road-tiles.xml" />

This will load "road-tiles.xml" into the resource's namespace. If you wish to avoid id clashes you may supply a namespace:

<require file="road-tiles.xml" namespace="road" />

If a namespace is given then the element ids from the "road-tiles.xml" will be prefixed by the namespace and a period, e.g. "road.bitumen".

Other tags within <resource> are:

<image file="" id="">

Loads file with pyglet.image.load and gives it the id which is used by tiles to reference the image.

<imageatlas file="" [id="" size="x,y"]>

Sets up an image atlas for child <image> tags to use. Child tags are of the form:

<image offset="" id="" [size=""]>

If the <imageatlas> tag does not provide a size attribute then all child <image> tags must provide one. Image atlas ids are optional as they are currently not reference directly.

<tileset id="">

Sets up a TileSet object. Child tags are of the form:

<tile id="">

[<image ...>]

</tile>

The <image> tag is optional; these tiles may have only properties (or be completely empty). The id is used by maps to reference the tile.

<rectmap id="" tile_size="" [origin=""]>

Sets up a RectMap object. Child tags are of the form:

<column>

<cell tile="" />

</column>

Most tags may additionally have properties specified as:

<property [type=""] name="" value="" />

Where type is one of "unicode", "int", "float" or "bool". The property will be a unicode string by default if no type is specified. The properties are loaded into a dictionary called ".properties" on the appropriate Image, Tile, Map and Cell instance.