read-write TileMapAtlas (at last ;)

The TileMapAtlas object was introduced in cocos2d v0.5.0. Although it helped in creating big scenarios, a lot of functionality was missing, like the possibility to read and modify the atlas in runtime, isometric tiles, hex tiles, animations, etc.

From cocos2d v0.7 onwards, you can read/write the TileMapAtlas (the rest of the features will be included in v0.8)

So, how I do a read / write my TileMapAtlas in v0.7 ?

Let's start by recalling how to create a TileMapAtlas. The API is same you were using since v0.5:

TileMapAtlas *tilemap = [TileMapAtlas tileMapAtlasWithTileFile:@"tiles.png" mapFile:@"levelmap.tga" tileWidth:16 tileHeight:16];
[self add:tilemap];

Since v0.7 you can read/write the TileMapAtlas but if you don't want to, you might want to release the map from memory:

// Release the map from memory ONLY if won't read or write the tile map
[tilemap releaseMap];

But if you are going to read or write the map, DON'T release the memory. Otherwise, you won't be able to read or modify the atlas.

To read the the value of a certain tile, or to iterate over all the tiles you can do the following:

// For example you can iterate over all the tiles
// using this code, but try to avoid the iteration
// over all your tiles in every frame. It's very expensive

for(int x=0; x < tilemap.tgaInfo->width; x++) {
for(int y=0; y < tilemap.tgaInfo->height; y++) {
 ccRGBB c =[tilemap tileAt:ccg(x,y)];
 if( c.r != 0 ) {
    // only the channel 'r' (red) is used
    // if r == 0 it means that it is transparent, it won't be rendered
 }
}
}

And to modify a certain tile of the TileMapAtlas object you can do as follows:

int x = 20;
int y = 30;

// read value
ccRGBB c =[tilemap tileAt:ccg(x,y)];

// modify it
c.r = 21;

// and store it on the tile map atlas
[tilemap setTile:c at:ccg(x,y)];

Limitations: you can't modify a position whose tile value is 0. If you know that you are going to modify a certain position of the atlas, don't set the initial value with 0.

For more information see the AtlasDemo example: TestAtlas.m