2.1. Quickstart Guide Document

Previous: Getting Started - Overview - Next: Working with MapsReturn to Index

Prepare a TMX Tilemap

First, create a TMX file with accompanying tilesets, or use an existing map. Use the free Tiled Map Editor to edit tilemaps. Refer to the Tiled documentation for instructions.

See the bottom of this article for important information regarding Tilesets.

Add map and images to the Xcode Project

The TMX file, its tileset images, and any external tilesets (TSX) it references must be added to the Xcode project and included in the target you are building.

You can also add additional high-res tileset images with @2x/@3x suffixes, or the corresponding Cocos2D suffixes (-hd etc.). They will be used automatically on corresponding devices.

Caution: Always use the lowest-resolution image in a tileset, not the @2x/@3x/-hd image variants! You only need a single TMX file without any suffixes to support multiple device resolutions.

Tip: Be sure to setup Xcode groups vs folder references correctly when adding files. It is easiest to simply store TMX and tileset images in the same folder. By default, Xcode adds all resource files to the root folder of the app bundle, regardless of Xcode groups.

Import TilemapKit

At the beginning of the source file you wish to use TilemapKit in, add:

#import "TilemapKit.h"

// Swift users need not import TilemapKit (it's in the Bridging Header)!

Load the TMX File

To load a map from a TMX file:

TKMapNode* mapNode = [TKMapNode mapNodeWithContentsOfFile:@"strategy.tmx" renderSize:CGSizeZero];
[self addChild:mapNode];

// Swift
let mapNode = TKMapNode(contentsOfFile:"strategy.tmx", renderSize:CGSizeZero)

This loads the TMX file and renders the map. Assuming self is the scene, the map would be drawn anchored to the lower-left corner of the screen.

Add Nodes to Map Layers

Then get a layer by its name, and cast accordingly:

TKTileLayerNode* gameLayerNode = (TKTileLayerNode*)[mapNode layerNodeNamed:@"Game Layer"];

// Swift
let gameLayerNode = mapNode.layerNodeNamed("Game Layer") as! TKTileLayerNode

Now you can start modifying the layer, for example moving it by running a move action or changing its position property.

You can also add children to layers (the map node doesn’t accept children other than layer nodes):

[gameLayerNode addChild:player];

// Swift

The player’s position will be relative to the layer. If the player’s position is 0,0 it will be drawn in the layer’s lower-left corner.

Also look into the TKMapNodeDelegate protocol and TKMapNode’s delegate property for a way to add custom nodes based on objects on an object layer.

Important Map Editing Tips

Use a supported Map Format

In Tiled, with a map already open, choose Map => Map Properties from the menu. In the properties pane, locate the property named Tile Layer Format. You’ll also find this setting in the New Map dialog when creating a map from scratch.

The Tile Layer Format must be set to one of these, recommendation in bold:

  • Base64 (uncompressed)
  • Base64 (gzip compressed)
  • Base64 (zlib compressed)

We recommend using Base64 (zlib compressed) as this will reduce the TMX file size and will load the TMX file faster than gzip compressed files, and for any map but tiny maps it’ll also load faster than an uncompressed map.

Pay attention when adding tileset images!

Caution Tileset images have to be in the same folder as the TMX file! Or in a subfolder relative to the TMX file's location.

Not having the tileset image in the same folder or subfolder of the TMX file when adding the image to a new tileset prevents the TMX file from being opened on other computers/accounts, and will definitely fail to load when building an app.

Relative paths are bad!

Tiled will store the relative path to images that are not in the TMX’s folder or a subfolder thereof. Inside the TMX file you may see paths similar to this one:


Relative paths only resolve correctly on your local computer, possibly even just for your account. You can’t share a map with relative paths, nor use it in an app bundle.

This issue is so prevalent that TilemapKit will abort loading TMX files if there’s an image path that contains a relative component, ie the string: “../” - even though this means certain possibly “legal” setups will also raise this error.

Fixing a Map already containing relative paths

Should you already have a map with tileset images referenced by relative paths, you have to manually fix this:

  • Close Tiled, then open the TMX file in a text editor (ie Xcode).
  • Search for and remove all occurances of ../ in image source attributes.
  • Copy or move the tileset images to the correct location relative to the TMX file.
  • Open the TMX file in Tiled.
    • If Tiled won’t open the map, the file locations and image paths inside the TMX file and in Finder don’t match.

It’ll be easiest to simply remove all path components from image filenames inside the TMX file, then copy the images to the same folder as the TMX file.

Paths pointing to subfolders relative to the TMX file’s folder will also work but require a folder reference for the subfolder in Xcode.

Always include the tileset images

Tileset images are not embedded in TMX files!

Tileset images remain separate files and need to be added to the Xcode project along with the corresponding TMX or TSX file.

You can of course provide additional @2x/@3x/-hd/etc. tileset images for high-resolution Retina devices. They will be used automatically when available and depending on the device.

If in doubt: store TMX, TSX & PNG files in the same folder

We recommend to store all related tilemap files in the same folder as the TMX file. This means each TMX map’s additional files (tileset image(s) and/or TSX file(s)) should all be stored in the same folder as the TMX file.

Assuming a coherent naming scheme, it’ll remain relatively convienent to have all TMX, TSX and tileset images in the same folder. This is assuming you’ll properly group the files in Xcode, and use Xcode most of the time to open tileset images and TMX/TSX files.

You can do so by double-clicking TMX/TSX files or by right-clicking and choosing Open with External Editor. Both times Tiled will open the file or switch to the file’s tab.

There’s really not much to win by “organizing” the TMX/TSX/Tileset files into physical folders. In fact, not doing so will make it easier to work with Tiled, too.

That’s not to say that you can’t arrange TMX/TSX/Tileset files in subfolders. However you can not have tileset images or TSX files in a folder above or parallel to the folder where the TMX file is located, as this would introduce a relative path. The TSX/PNG files can only be in a subfolder of the folder containing the corresponding TMX file.

If you do use subfolders, be sure to add the corresponding folder as Folder Reference in Xcode (blue folder icon) so that the relative paths are preserved.

Recommended: External Tilesets

We also recommend to get in the habit of creating and using external Tilesets (.TSX files) extensively.

TSX tilesets have the huge benefit that every edit to a TSX tileset will be reflected in every TMX map using this TSX tileset. This means you’ll only have to edit those tile(set) properties, tile collisions and tile animations once, rather than once for every map!

Previous: Getting Started - Overview - Next: Working with MapsReturn to Index