［稍后］

Tiled Maps

There 2 ways of creating tiled maps in cocos2d.

• by using the TMX Tile Map format (newer, more flexible, recommended)
• by using the PGU Tile Map format (older, deprecated)

TMX Tile Map format

Since v0.8.1, you can use tile maps created with Tiled in your game.

Tiled is java application that runs on OS/X, Windows and Linux. This page explains how to create a map using Tiled:

• Creating a single map with Tiled

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).
  • cocos2d v0.8.1 supports only 1 tileset for all the layers
  • cocos2d v0.8.2 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 TMXLayer (which is a subclass of AtlasSpriteManager)
  • Each tile will be represented by an AtlasSprite (it's parent will be the TMXLayer)

How to create embedded tilesets with external images

cocos2d doesn't support embedded images in tilesets (but requires tilesets themselves to be embedded in the map file). Instead you should create a sprite sheet image (AKA: Texture Atlas) by yourself.

Setting the Tiled preferences

Tell tiled to NOT save the tileset with embedded images:

$ cd bin/tiled-0.7.2/
$ java -jar tiled

Once in tiled, you should do:

• Edit → Preferences → Saving
• Layer Options:
  • Use binary encoding: ON (“text” encoding is not supported by cocos2d)
  • Compress layer data: ON (non-compressed data is also supported)
• Tilset Options:
  • Embed images (PNG): OFF (Embedding images is not supported)

Note that when creating a new map, Map Size refers to the number of tiles vertically and horizontally, and not the pixel dimensions of your map. Note that there are limits to the size map the iPhone will support (user comment: we have seen 100 x 100 at 44px by 44px as working, but 400 x 200 not work - the tiles are all drawn black)

Making sure a tileset is embedded

The tilesets for your map must be embedded into the map file. In Tiled this is controlled in the “Tileset Manager” (accessed via: Tilesets → Tileset Manager ). You should see ”(Embedded)” in the column to the right of the tileset name in the list of tilesets. If you instead see a path string, you need to select that row in the list and then select the Embed icon to the right which will convert it to an embedded tileset.

If you are using a different tool or want to confirm for yourself you can open the *.tmx file in a text or XML editor and check the<tileset> node. If it contains a source property with a file name you are looking at an external tileset which will not work with cocos2d-iphone.

Creating sprite sheets

There are some image packers that might be useful:

• mkatlas.pl a command line texture atlas creator (perl)
• zwoptex a visual texture atlas creator (flash)
• Packer a visual texture atlas creator (java)

These tools let you create sprite sheets from individual images.

Limitations of the sprite sheet:

• Max size: 1024×1024 (which is the maximum size supported by iPhone 3G)
• The tiles should all have the same size

Options:

• margin: the space in pixels in the margins
• spacing: the space in pixels between the tiles

It is recommended that you use a margin of 2, and spacing of 2

The spritesheet artifact fixer

The spritesheet-artifact-fixer is a little tool that comes with cocos2d that lets you fix your spritesheet.

What it really does, is to copy the borders of your tiles, into the spacing/margin pixels. In theory the spacing/margin pixels should NOT be rendered, but in practice sometimes they are rendered, specially if you use anti-alias textures and a 3D projection.

How to use this tool:

$ cd cocos2d/tools
$ python spritesheet-artifact-fixer.py -f spritesheet.png -x 32 -y 32 -m 2 -s 2

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

GID

A 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

TMXTiledMap *map = [TMXTiledMap tiledMapWithTMXFile:@"hexa-test.tmx"];
[self addChild:map];

All the tiles by default will be aliased. If you want to create anti-alias tiles, you should do:

 
// create a TMX map
TMXTiledMap *map = [TMXTiledMap tiledMapWithTMXFile:@"orthogonal-test2.tmx"];
[self addChild:map];
 
// iterate over all the "layers" (atlas sprite managers)
// and set them as 'antialias' 
for( TMXLayer* child in [map children] ) {
    [[child texture] setAntiAliasTexParameters];
}

Full example:

• tests/TileMapTest.m

How to get/add/delete/modify a tile

To obtain a tile (AtlasSprite) at a certain coordinate

TMXTiledMap *map = [TMXTiledMap tiledMapWithTMXFile:@"orthogonal-test2.tmx"];		
TMXLayer *layer = [map layerNamed:@"Layer 0"];
 
AtlasSprite *tile = [layer tileAt:ccp(0,63)];
tile.anchorPoint = ccp(0.5f, 0.5f);

To obtain a tile's GID at a certain coordinate

TMXTiledMap *map = [TMXTiledMap tiledMapWithTMXFile:@"orthogonal-test2.tmx"];		
TMXLayer *layer = [map layerNamed:@"Layer 0"];
 
unsigned int gid = [layer tileGIDAt:ccp(0,63)];

To set a new tile's GID's at a certain coordinate

TMXTiledMap *map = [TMXTiledMap tiledMapWithTMXFile:@"orthogonal-test2.tmx"];		
TMXLayer *layer = [map layerNamed:@"Layer 0"];
 
[layer setTileGID:gid2 at:ccp(3,y)];

To remove a tile at a certain coordinate

TMXTiledMap *map = [TMXTiledMap tiledMapWithTMXFile:@"orthogonal-test2.tmx"];		
TMXLayer *layer = [map layerNamed:@"Layer 0"];
 
[layer removeTileAt:ccp(15,15)];

To iterate a Layer

TMXTiledMap *map = [TMXTiledMap tiledMapWithTMXFile:@"orthogonal-test2.tmx"];		
TMXLayer *layer = [map layerNamed:@"Layer 0"];
 
CGSize s = [layer layerSize];
for( int x=0; x<s.width;x++) {
	for( int y=0; y< s.height; y++ ) {
		unsigned int tmpgid = [layer tileGIDAt:ccp(x,y)];
		[layer setTileGID:tmpgid+1 at:ccp(x,y)];
	}
}

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)

PGU Tile Map Format

Since cocos2d v0.5.0, you can use the PGU Tile maps.

Since the format is not very flexible (is has limitations with it's sizes) and the editor seems to has some bugs, this format is deprecated since v0.8.1. You will be able to continue using it with your old game, but it's usage is not recommended.

Instead, use the recommened TMX Tile Map.

Some articles about this format:

• read/write in TileMapAtlas
• How to use the PGU tile editor
• Plugin to generate PGU maps with the Tiled editor