Tilemap Framework for SpriteKit & Cocos2D

TilemapKit is the first complete hexagonal, isometric (staggered & isometric) and orthogonal TMX tilemap framework for SpriteKit and Cocos2D.

  • Hexagon Map, "pointy top" facing upwards (Stagger Y), with 3D tiles
    Hexagon Map, "pointy top" orientation (tiles by Kenney), rendered by TilemapKit

TilemapKit draws all map orientations and stagger variations. It can read and write TMX files created with Tiled Map Editor, with or without compression. Maps can be completely modified at runtime. Coordinate conversion, neighbor tile coordinates, tile corner offsets, and many more convenience features included.

GameplayKit features built-in: create grid graphs from blocked/walkable tiles or using tile costs, editable as properties in Tiled. Or create obstacle graphs from polygon, rectangle and circle objects, or using tile-shaped vertices. Note: GameplayKit features require iOS 9 / OS X 10.11.

TilemapKit comes with dozens of example TMX files, free tilesets and demo projects. See the gallery above.

How is TilemapKit better than JSTilemap and CCTiledMap?

The other solutions only support a small set of features offered by Tiled. They do not support all map orientations, specifically: hex maps and staggered isometric support.

They don’t load all TMX features: for instance tile collisions, tile animations, terrain information is completely absent, and runtime access to existing features (ie tile GID array) is limited.

There’s little to no support and artifacts (“black lines”) are common. In particular the performance of  JSTilemap for maps larger than the screen decreases with the size of the map.

Have I mentioned the sketchy @2x, @3x support? In CCTiledMap you have to resort to making copies of your TMX file, one for each resolution.

Which Cocos2D?

TilemapKit is compatible with v3.x of both Cocos2D-SpriteBuilder and Cocos2D-ObjC (formerly known as cocos2d-iphone / cocos2d-swift).

TilemapKit does not work with Cocos2D-X. Disappointed? Vote for a port!

Aren’t Tilemaps trivial?

No. Not at all.

In case you’re thinking “draw a couple sprites on a grid, done – what’s the big deal?” know that only orthogonal Tilemaps are that trivial, and only if you inefficiently draw all tiles, even those outside the screen bounds.

There’s a substantial amount of trigonometry for coordinate conversion and rendering required. Performance optimizations are critical for tilemaps, thus not drawing tiles outside the screen is a must have, as is multithreading the tile render loop.

Fixing artifacts requires applying stringent rules to positioning tiles, and possibly stretching textures without distorting the map. Not to mention reading and writing zlib compressed, base64 encoded TMX files.

And there’s a lot more!

A grid path on a staggered map means you’ll have to account for the fact that coordinates aren’t evenly distributed, they “jump” by +2/+0 or by +1/-1 every other row, depending on stagger settings.  This basically changes every indexing algorithm from the basic orthogonal y * width + x to something much, much more complex.

All of this, and more, is already taken care of for you if you use TilemapKit. And if there’s something missing, let us know, we’ll be happy to add it if it’s of general interest.

When … ?

TilemapKit will be available soon, early August 2015.


TilemapKit is a project by frustrated tilemap game developers Steffen Itterheim (aka LearnCocos2D, author of Learn Cocos2D and Learn SpriteBuilder) and Marcus Lubczyk.