1. Installation Guide Document

Next: Getting Started - OverviewReturn to Index


This article describes the necessary steps to integrate TilemapKit in an existing Xcode Project. The steps are the same for iOS and OS X projects. Swift users also need to create/update the Swift bridging header.

Integrating the Source Code

  1. Copy the TilemapKit folder into your project’s root folder (where the .xcodeproj is).
  2. In Xcode, add all TilemapKit source files to the project (File -> Add Files to ..).
    • Note: Verify that the files are assigned to the correct target(s). In Xcode 7 the target selection list is hidden behind the Options button in the Choose Files dialog.
  3. Select the app’s build target, then switch to the Build Settings tab, where you need to:
    1. Update the Header Search Paths setting:
      • Enter the path (relative to .xcodeproj or absolute) to the TilemapKit folder.
      • For example:"TilemapKit/**" (The /** suffix means: recursive)
    2. Ensure Minimum Deployment Target is set correctly:
      • iOS 8 or OS X 10.9: if you don’t intend to use GameplayKit features.
      • iOS 9 or OS X 10.11: if you intend to use GameplayKit features.
  4. Switch to Build Phases tab and go to the Link Binary with Libraries list:
    • Add libz.dylib (zlib) to the list.
    • Also add GameplayKit.framework if you intend to use GameplayKit features.
  5. (TilemapKit for Cocos2D Framework Users Only): You must remove or disable any existing references to Cocos2D source files. Not doing so will result in linker errors (duplicate symbols) or (seemingly random) crashes. Cocos2D is already compiled into the TilemapKit.framework out of necessity.

Swift Integration

To enable Swift support, you’ll need to create a bridging header if there isn’t one already in your project.

Create a Bridging Header

Xcode will ask you to create a Bridging Header for you when first importing Objective-C source files to a Swift project. Allow this.

Otherwise, if there’s no Bridging Header file already in the project, here’s what you need to do:

  • Run File => New => File.
  • Choose the Header File template from the Source section, click Next.
  • Name the file Swift-Bridging-Header.h (or any other name).
  • Select your project’s app target, switch to the Build Settings tab.
  • Locate Objective-C Bridging Header under Swift Compiler - Code Generation.
  • Enter the relative path and filename of the bridging header. For instance: Source/Swift-Bridging-Header.h.
    • Note: the path is relative to the project’s root folder, where the .xcodeproj file is.

Import TilemapKit

In the Swift Bridging Header, add the following line:

#import "TilemapKit.h"

This makes the TilemapKit classes and types available in Swift code.

It is not needed to add import TilemapKit to Swift source files. In fact, doing so could lead to compile errors (at least it did in a Xcode 7.0 beta version).

Troubleshooting & Tips

  • If you intend to use GameplayKit features you must be using Xcode 7.0 or newer.
  • If you get header not found errors, double-check the Header Search Paths setting resolves to the correct path and folder.
    • Most importantly: if there are any spaces (or other characters that are neither letter nor digit) in any folders in the path, you must escape the search path with double quotes, for instance: "Tile Map Kit++/**"
    • Tip: It is strongly recommended to avoid any “special characters” in the path leading up to a source code project. Even to this date, many tools and scripts will fail to work correctly when they need to operate on or in paths that contain spaces or non-letter, non-digit characters. It is sad but true.
  • If there are issues related to libz / zlib:
    • Cocos2D users may already have -lz flag set in Other Linker Flags under Build Settings. If that is the case, you do not need to explicitly link with libz.dylib. This shouldn’t be a problem but just to be sure …
    • Always link against libz.dylib and not any of the versioned libs, ie don’t use libz.2.2.1.dylib.
  • If you try to build TilemapKit into a static library or framework target, you must:

    • Add -ObjC to the app target’s (not the library/framework target!) Other Linker Flags Build Setting.
    • Otherwise category methods will not be available, leading to “unrecognized selector” errors.
  • You may experiment with lowering the Minimum Deployment Target.

    • No guarantees. Support limited to recommendations and straightforward solutions. No backward compatibility code fixes for unsupported OS versions.
    • Most deployment target issues are straightforward to solve, either by disabling the feature (if not needed, for instance within a debugging class) or by using an older API or workaround. This often involves doing a few more extra steps or simply calling a different method or passing different parameters.
    • Since I’ve had this discussion numerous times before: my rule of thumb is to support “current OS version minus one” for new projects. It may be “minus two” if the latest release will certainly be less than 6 months old by the time of your app’s release. Supporting OS versions older than that makes little sense.
    • Also consider the time it takes to develop the app, ie its release date. Many make the mistake looking at what the state of OS usage is now but forget that their optimistically planned 3-month project will actually not be in the store for at least another 5+ months from now. ;)
    • Refer to Apple’s own statistics. At the time of this writing shortly before release of iOS 9, the adoption rate of iOS 7 was only 13%, earlier versions 2%. This is actual App Store users - so users who actually download or buy apps, or are merely browsing the store! There may be many more older devices, but their users don’t visit the App Store anymore - which is the one and only metric app developers need to consider when deciding on OS version support.

Next: Getting Started - OverviewReturn to Index