Developers Manual > Cocos2d-x > Advanced Features > TileMap

TileMap

Tiled Map

Tile map is built to be easy to use, yet flexible enough to work with Cocos2D-x, whether your game is an RPG, platformer or Breakout clone. Cocos2D-x supports maps created with the open source Tiled Map Editor and saved in TMX format.

Cocos2d supports the following TMX maps:

Orientation:

  • Orthogonal maps

  • Isometric maps

  • Hexagonal maps (edges on left-right. edges at top-bottom are not supported… it seems that Tiled doesn’t support them either)

Tiles:

  • Embedded tiles are NOT supported (i.e., tilesets with embedded images).

  • Only embedded tilesets are supported (i.e., the tileset is embedded, but not its images).

  • supports at most 1 tileset per layer.

Layers:

  • You can have as many layers are you want

  • Each layer will be represented internally by a CCTMXLayer (which is a subclass of CCSpriteSheet)

  • Each tile will be represented by an CCSprite (its parent will be the CCTMXLayer)

Object Groups:

  • Tiled objectGroups are supported as well

Coordinates and GIDS

Coordinates

The coordinate system used in Tiled in a 64×32 map is:

  • (0,0): top-left corner

  • (63,31): bottom-right corner

GIDA

tile’s GID is the tile’s Global IDentifier. It is an unsigned int that goes from 1 until the quantity of tiles.

If you have 5 different tiles then:

  • Tile 0 will have GID 1

  • Tile 1 will have GID 2

  • Tile 2 will have GID 3

  • and so on.

The GID 0 is used to represent to empty tile.

How to create a TMX node

C++

1
2
3
4
5
6
7
8
9
// create a TMX map
auto map = TMXTiledMap::create("TileMaps/iso-test-vertexz.tmx");
addChild(map, 0, kTagTileMap);

// all tiles are aliased by default, let's set them anti-aliased
for (const auto& child : map->getChildren())
{
    static_cast<SpriteBatchNode*>(child)->getTexture()->setAntiAliasTexParameters();
}

Lua

1
2
3
4
5
6
7
8
9
// create a TMX map
local  map = cc.TMXTiledMap:create("TileMaps/iso-test-vertexz.tmx")
layer:addChild(map, 0, kTagTileMap)

// all tiles are aliased by default, let's set them anti-aliased\n
local children = map:getChildren()
for k, child in ipairs(children) do
    child:getTexture():setAntiAliasTexParameters()
end

How to get/add/delete/modify a tile

To obtain a tile (Sprite) at a certain coordinate
C++

1
2
auto layer = map->layerNamed("Layer 0");
auto tile = layer->tileAt(Vec2(1, 63));

Lua

1
2
local layer = map:layerName("Layer 0");
local tile = layer:tileAt(cc.p(1, 63))

To obtain a tile’s GID at a certain coordinate
C++

1
unsigned int gid = layer->tileGIDAt(Vec2(0, 63));

Lua

1
local git = layer:tileGIDAt(cc.p(0, 63))

To set a new tile’s GID’s at a certain coordinate
C++

1
2
3
4
 layer->setTileGID(gid, Vec2(3.0f, (float)3));

// To remove a tile at a certain coordinate
layer->removeTileAt(Vec2(5.0f, 5.0f));

Lua

1
2
layer:setTileGID(gid, cc.p(3, 3))
layer:removeTileAt(cc.p(5, 5))

To iterate a Layer
C++

1
2
3
4
5
6
7
8
Size s = layer->getLayerSize();
for (int x = 0; x < s.width; ++x)
{
    for (int y = 0; y < s.height; ++y)
    {
        layer->setTileGID(newGid, Vec2(x, y));
    }
}

Lua

1
2
3
4
5
6
local s = layer:getLayerSize()
for x = 0, s.width - 1, 1 do
    for y = 0, s.height - 1, 1 do
        layer:setTileGID(newGid, cc.p(x, y))
    end
end

z order and depth buffer

Information valid both for Isometric and Orthogonal maps. NOT valid for Hexagonal maps

If your game needs to place the sprites behind/in front of certain tiles according to the sprites’ Y position (a common scenario in isometric maps, and in some orthogonal maps too), then you have 2 options:

  • Use OpenGL ES depth buffer

  • Use multiple TMX Layers and z-order

Using Depth Buffer

It is very important to create a map with 2 TMX Layers

  • A background layer. eg: grass

  • A foreground layer. eg: trees

The grass layer will be behind the sprites, so its vertexZ value should be the lowest possible value. eg:-1000. The trees layer should have different vertexZ values for the tiles. Tiles that are at the bottom should have higher vertexZ than the tiles that are at the top.

So, in order to achieve this, you should only do:

  • Open Tiled
  • Select the background Layer
  • Tiled → Layer → Layer Properties
  • Add: cc_vertexz =-1000
  • Select the foreground Layer (eg: trees)
  • Tiled → Layer → Layer Properties
  • Add: cc_vertexz = automatic

Examples:

Isometric vertex Z example. It has 2 layers: “trees” and “grass”. Uses cc_vertex=automatic for the “trees” layer. And cc_vertexz=–1000 for the “grass” layer.
Orthogonal vertex example. It has 2 layers: “trees” and “grass”. It uses cc_vertexz=automatic and cc_alpha_func=0.5 for the “trees” layer. and cc_vertexz=–1000 for the “grass” layer.

Using multiple TMX Layers and z-order

Each layer in the map is automatically assigned it’s own zOrder value, so there is no need to add any layer attributes in your TMX editor. Adding your sprite as a child of the TMXMap allows you to dynamically place it within the layers of the map object.
C++

1
2
3
4
5
auto tamara = Sprite::create("tamara.png");
auto p = tamara->getPosition();
p = CC_POINT_POINTS_TO_PIXELS(p);
float newZ = -(p.y + 32) / 16;
tamara->setVertexZ(newZ);

Lua

1
2
3
4
5
local tamara = cc.Sprite:create("tamara.png")
local p = tamara:getPosition()
p = CC_POINT_POINTS_TO_PIXELS(p)
local newZ = -(p.y + 32) / 16
tamara:setVertexZ(newZ)

Screenshots

Orthogonal map, with 3D projection and anti-aliased tiles. The tiles were “fixed” using the spritesheet-fixer tool. No artifacts appears even with a 3D projection and anti-aliased tiles
Orthogonal map. map’s tile size is smaller than the tiles
Isometric map, with 2D projection and aliased tiles
Hexagonal map, with 2D projection and aliased tiles. Edges are at the left-right. Bottom-top edges are not supported (yet)

References

cocos2d-iphone tiled_maps

Creating a simple map with Tiled

how to make a tile based game with cocos2d

tile.png (35.3 kB) iven, 2013-01-21 09:54

GIDA.png (55.6 kB) iven, 2013-01-21 09:54

layers.png (26.7 kB) iven, 2013-01-21 10:00

grass.png (25.3 kB) iven, 2013-01-21 10:00

tree.png (27.3 kB) iven, 2013-01-21 10:03

vertexZ.png (92.8 kB) iven, 2013-01-21 10:17

vertex.png (78.9 kB) iven, 2013-01-21 10:17

zorder.png (96.8 kB) iven, 2013-01-21 10:17

Orthogonal.png (78.3 kB) iven, 2013-01-21 10:23

Orthogonal2.png (104.6 kB) iven, 2013-01-21 10:23

Hexagonal.png (163.2 kB) iven, 2013-01-21 10:23

Isometric.png (36.7 kB) iven, 2013-01-21 10:23

Sign up for our newsletter to keep up with the latest developments, releases and updates for Cocos2d-x.