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.
- Copy TilemapKit-Framework folder to your project’s root – where your .xcodeproj is located.
- Add the TilemapKit-Framework/TilemapKit-Framework.xcodeproj to your Xcode project.
- 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)
- 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_COCOS2D depending on which engine you are using. Leave empty if using a custom engine.
- Other Linker Flags: add
- 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:
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
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:
- a “model” library
- 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 Kit||Cocos2D
|iOS App||libTilemapKit-Model iOS.a|
|Mac App||libTilemapKit-Model 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
- When using Cocos2D: add the macro
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):
Your editing results should look similar to this:
-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:
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.