Sprite Kit Tilemaps: Free TilemapKit Beta

Currently the beta supports Sprite Kit Tilemaps for iOS and Mac, with Swift and Objective-C example projects.
Cocos2D beta is coming soon.

Looking for Sprite Kit Tilemaps support?

Download the free TilemapKit Beta here!

The beta comes as working Xcode projects with both Swift and Objective-C versions, both ready to build and run.

Sprite Kit Tilemaps ExampleWith the instructions in above link you should be able to use the beta TilemapKit.framework in your own project.

A lot of time and effort was spent on supporting all Tiled (TMX) map type variations: orthogonal, isometric and staggered isometric, hexagonal with “pointy” and “flat” side up, even and odd stagger indexes, X and Y stagger axis.

Plus accurate tile picking (screen to map and map to screen coordinate conversion) for all map types and all map variations/settings.

And there’s more to come

Please leave me feedback on the TilemapKit beta in the forum or as a comment on this post.

TilemapKit Forum Online

The TilemapKit forum has been online for a couple days already.

I switched over to posting developer reports as well as answering questions on the forum. In case you’re wondering about the recent absence of blog posts.

How to install TilemapKit to an existing Xcode Project

Install TilemapKit to an existing Xcode Project

This guide is for installing the source code of TilemapKit. We are looking into providing a drag & drop solution by including a binary-only TilemapKit.framework.

This guide explains how to install TilemapKit to an already existing Xcode project, whether it uses Sprite Kit or Cocos2D, or is targeting the Mac or iOS platform. The instructions are easy and straightforward. Depending on your expertise you can follow the quick install or the detailed instructions.

Quick Install Instructions (Requires Xcode Skill Level 30+)

For those who know how to find their way around Xcode and who know what is needed to add a 3rd party library, follow the quick instructions below.

If you do run into any problems following the quick install instructions, be sure to check the detailed instructions below to verify your steps before reporting a problem, thank you.
  1. Copy TilemapKit-Framework folder to your project’s root – where your .xcodeproj is located.
  2. Add the TilemapKit-Framework/TilemapKit-Framework.xcodeproj to your Xcode project.
  3. In your target’s Build Phases, add two TilemapKit libraries to the Link Binary With Libraries list:
    • Exactly one (1) “model” and one (1) “engine” library
    • Pick the correct libraries based on target platform (iOS or Mac) and engine (SpriteKit or Cocos2D)
  4. Edit your targets’s Build Settings (edit both Debug & Release as needed):
    • Header Search Paths: add TilemapKit-Framework and mark it as recursive
    • Preprocessor Macros: add TK_RENDERER_SPRITEKIT or TK_RENDERER_COCOS2D depending on which engine you are using. Leave empty if using a custom engine.
    • Other Linker Flags: add -lz -ObjC
  5. Using Swift?
    • Open the bridging header as indicated by Build Setting Objective-C Bridging Header. If setting is empty: create a bridging header, add its name/path to the aforementioned build setting.
    • Add the following lines to the bridging header:
      #import "TKTilemap.h"
      #import "TKTilemapNode.h"

Copy TilemapKit-Framework

First, copy the TilemapKit-Framework folder to your project’s root folder using Finder.

Note: The root folder is where the project’s .xcodeproj is located, as indicated in the screenshot below.


Copy TilemapKit-Framework to your Xcode project’s root folder

Add TilemapKit-Framework.xcodeproj

For this step you need to have your existing project open in Xcode. Switch to the Project Navigator pane – that’s the Finder-like tree view with the file hierarchy on the left side.

Select a group where you want to add the TilemapKit project to. The actual location doesn’t matter. If you’re undecided, just select the project itself (topmost icon). Then choose File -> Add Files to “..” from the menu. This will bring up the following dialog:


Browse into the TilemapKit-Framework folder and select the TilemapKit-Framework.xcodeproj.

Before clicking Add, make sure that Copy items if needed is unchecked, that Create groups is selected and that the Add to targets list has the app’s target checked (respectively all targets that you want to use TilemapKit in). Then you can click Add.

Your project now includes a reference to the TilemapKit-Framework project, as seen below.


TilemapKit Xcode project was added correctly

Linking with TilemapKit Libraries

Repeat this and all following step for all targets that need to link with TilemapKit. Most users will only need to do this once for their app’s target.

Select your project and then select the app’s target. Switch to the Build Phases tab. Unfold the Link Binary With Libraries pane, then click the Add (+) button (same process as steps 1-4 here). You’ll see a list of libraries, if necessary filter the list by entering “tilemap” in the box at the top:


List of TilemapKit libraries

Which TilemapKit Libraries to link with?

You will need to link with exactly two TilemapKit libraries, no more and no less:

  1. a “model” library
  2. a “engine” library

All libraries additionally exist in two flavors for the two supported platforms: iOS and Mac. Use the matrix below to find out which two libraries you need to add to your project.

 Sprite KitCocos2D
iOS ApplibTilemapKit-Model iOS.a
libTilemapKit-SpriteKit iOS.a
libTilemapKit-Model iOS.a
libTilemapKit-Cocos2D iOS.a
Mac ApplibTilemapKit-Model Mac.a
libTilemapKit-SpriteKit Mac.a
libTilemapKit-Model Mac.a
libTilemapKit-Cocos2D Mac.a

For example, if you use Sprite Kit and you are building a Mac app, you would have to add libTilemapKit-Model Mac.a and libTilemapKit-SpriteKit Mac.a.

Ignore the fact that the added libraries are printed in red letters. This should change after the first successful build, but sometimes won’t (it’s an Xcode bug).

Configure your Target’s Build Settings

Lastly, switch to the target’s Build Settings tab to make some quick but important additions.

Add TilemapKit to Header Search Paths

Locate the Header Search Paths setting. Double-click the value to edit it. In the popup box, enter TilemapKit-Framework as the path, then change the setting to the very right so that it reads recursive. See the image below:


Make sure the path contains just the folder name, and is set to be recursive.

Should your project have different search paths for Debug & Release configurations you need to repeat this step for both Debug & Release configurations.

Set the engine-specific Preprocessor Macro

Locate the Preprocessor Macros setting. This setting will most likely have different values for Debug and Release configurations, so you need to repeat this step for Debug and Release builds. Double-click the value to edit it.

  • When using Sprite Kit: add the macro TK_RENDERER_SPRITEKIT
  • When using Cocos2D: add the macro TK_RENDERER_COCOS2D

In the example screenshot below the corresponding macro for a Sprite Kit project was added to both Debug and Release configurations:


Example use: TK_RENDERER_SPRITEKIT used in a Sprite Kit project

Add Other Linker Flags

Locate the Other Linker Flags setting. Double-click to edit it. Add the following flags if they do not exist yet, and verify that case matches (it’s ObjC not Objc nor objc):

  • -lz
  • -ObjC

Your editing results should look similar to this:


Add -lz -ObjC to Other Linker Flags (and ensure correct casing!)

Swift Only: create and/or edit Bridging Header

If your project uses Swift as its main language, you have to make additional changes.

Still in the target’s Build Settings, locate the Objective-C Bridging Header setting.

  • If the setting is empty: edit its value and enter TilemapKit-Framework/Swift-Bridging-Header.h to use the Bridging Header provided by TilemapKit. Done.
    • Note: you will have to create your own bridging header if you want to link with another Objective-C library. In that case just merge the contents of TilemapKit’s bridging header or follow the instructions below.
  • If the setting is not empty: locate the bridging header file (it may not appear in Xcode’s Project Navigator) and open it. Add the following two lines:
    • #import "TKTilemap.h"
    • #import "TKTilemapNode.h"

By adding the above two lines you make the TilemapKit API known to Swift.

If the TilemapKit classes won’t autocomplete, give it some time to index the TilemapKit classes. If that won’t help try restarting Xcode and run Product -> Clean Build Folder by holding down the Option key while in the Product menu.


Install TilemapKit: done. Next: enjoy TilemapKit! If you have any issues or questions, please leave a comment.

Tileset Collections for Tiled: Orthogonal, Isometric and Hexagonal

Three Tileset Collections on OpenGameArt.org

While browsing OpenGameArt.org I noticed that some good quality tilesets aren’t easily found (badly tagged or named) while there’s a bunch of low-quality tilesets and unrelated items spamming the search results.

So I put the best ones together and added them to the following collections:

Best Orthogonal TilesetsBest Isometric TilesetsBest Hexagonal Tilesets
best orthogonal tileset collection previewbest isometric tileset collection previewbest hexagonal tileset collection preview

Or browse my OpenGameArt collections.

I hope this will be helpful to some. Let me know if you found a quality tileset not in this list so I can add it.

PS: I shouldn’t need to mention this, but “best” is highly subjective and I actually hate to use the term for anything that’s non-factual. However, for the sake of sticking out and getting user’s attention I caved and voluntarily curled my toenails. smile

How to create Hexagonal Tilemaps in Tiled Map Editor

How to create Hexagonal Tilemaps in Tiled Map Editor v0.11 and later

Hexagonal tilemaps support was added in Tiled v0.11, released in January 2015. This article explains how to set up hexagonal tilemaps with “pointy top” and “flat top” orientation and you’ll learn what the various “stagger” settings do.

Download Tiled and our Hexagonal Tilesets

If you haven’t already, download Tiled for free and run it. Also grab our public domain hexagonal tilesets that you’ll be using in this tutorial:

Hexagonal Map Types: “flat top” vs “pointy top”

There are two orientations for hexagonal tilemaps which require different settings and tilesets. In this tutorial you’ll find the settings for “flat top” hexagonal maps on the left, and the settings for “pointy top” hexagonal maps on the right side.

"Flat Top" Hex Tiles"Pointy Top" Hex Tiles
"Flat Top" Tileset"Pointy Top" Tileset

Create a Hexagonal Tilemap in Tiled

In Tiled, create a new map (File -> New) and use the settings below depending on what type of map you want to create. You are free to use any Map Size. No need to ponder about this now, you can later resize the map easily via Map -> Resize Map.

"Flat Top" Hexagonal Map"Pointy Top" Hexagonal Map
Tiled "New Map" settings for "Flat Top" Hexagonal MapTiled "New Map" settings for "Pointy Top" Hexagonal Map

Note that the Tile Size setting in this dialog actually refers to the grid size. So if you have 3D-ish tiles or just tiles that overlap tiles above them, this size will be smaller on at least one axis (typically height) than the actual pixel size of the tiles in the tileset. Here, the grid size is 60×39 for our flat top tiles, and 60×52 for the pointy top tiles.

Add a Tileset with Hex Tiles

Use the Map -> New Tileset menu command to add a new tileset image.

"Flat Top" Tileset"Pointy Top" Tileset
Tiled Add "Flat Top" Hexagon TilesetTiled Add "Pointy Top" Hexagon Tileset

Notice that the tile size varies, “flat top” tiles are 60×60 in size while “pointy top” tiles are higher with 60×80 pixels. Both tilesets do not use any spacing and margin between tiles (spacing) or the image borders (margin).

Transparent color is not used because transparency is already provided by the PNG’s alpha channel. This is generally recommended because few engines these days still use color coding for find transparent areas. The days of bit-blitting images into the framebuffer are long gone but gives me a reason to add this link for those interested in some background on 2D computer graphics.

Draw some tiles to try it out

It doesn’t look quite right, does it?

"Flat Top" with default settings"Pointy Top" with default settings
"Flat Top" hex map with incorrect settings"Pointy Top" hex map with incorrect settings

Let’s fix this by applying …

Correct Settings for Stagger Axis and Stagger Index

Choose the Map -> Map Properties command from the menu to bring up the map properties with the Stagger Axis, Stagger Index and Tile Side Length (Hex) settings. See also the announcement post for hexagonal tilemap support for further visualizations.

Tiled “Stagger Axis” Explained

The stagger axis for hexagon maps merely refers to the orientation (pointy top vs flat top), albeit in a non-intuitive way.

  • Set Stagger Axis to X for “Flat Top” hexagon tilemaps
  • Set Stagger Axis to Y for “Pointy Top” hexagon tilemaps

Now set the stagger axis in your map accordingly, depending on which tileset you are using.

Tiled “Stagger Index” Explained

The stagger index can be set to “even” or “odd” which simply changes which row or column is shifted (“staggered”). Whether it shifts rows or colums depends on the stagger axis setting.

  • Set the Stagger Index to Even to offset even-numbered columns (Stagger Axis: X) or rows (Stagger Axis: Y), ie 0, 2, 4, 6
  • Set the Stagger Index to Odd to offset odd-numbered columns (Stagger Axis: X) or rows (Stagger Axis: Y), ie 1, 3, 5, 7

Which setting you use for stagger index is largely a matter of personal or technical preference.

Tiled “Tile Side Length (Hex)” Explained

The hex side length basically determines tile overlap for hexagonal tilemaps. This overlap is always along the Stagger Axis, ie for Stagger Axis X the hex side length determines horizontal spacing between tiles.

The Tile Side Length value needs tweaking to get it right, and also depends on the design of the hex tileset. For example some tilesets are designed with a small amount of overlap (1-2 pixels) between tiles in mind. A good starting point is to take half the width of “flat top” (Stagger X) tiles respectively half the height of “pointy top” (Stagger Y) tiles.

  • Set the Tile Side Length (Hex) of your “flat top” map to 30 (half of the tile width)
  • Set the Tile Side Length (Hex) of your “pointy top” map to 26 (half of the tile height)

Note that in Tiled odd-numbered values for Tile Side Length seemingly have no or only a miniscule effect. I’m not sure if this is by design, it certainly is a rounding/truncation problem associated with integer numbers. A tile rendering engine may show different results for odd-numbered Tile Side Length settings, so I would recommend to stick to even-numbered values.

Now enjoy editing hexagonal tilemaps with Tiled!

"Flat Top" Hex Map"Pointy Top" Hex Map
Tiled "pointy top" hex mapTiled "flat top" hex map