UPDATE: Sparrow 1.3 has now been released and it includes an updated and significantly enhanced AppScaffold project which makes most of the reasons to use SparrowBones redundant. I recommend you use the official AppScaffold project as a starting point now, rather than SparrowBones.

Sparrow-Framework is pretty awesome for quickly chucking together iOS games. But wouldn’t it be nicer if there was a handy Xcode 4 template to start from?

Your wish is my command! Presenting SparrowBones, a beautiful handcrafted Xcode 4 template:

It’s fairly simple and slightly hacky. Unlike the AppScaffold, which comes with Sparrow-Framework, it supports automatic rotation (because I always hold my iPhone the wrong way) and unit testing (because I’m crazy like that). The file in the project should guide you through the installation.

If you use it, you’ll notice 2 template projects in the SparrowBones section - “Game with Sparrow source copied” and “Game with Sparrow source linked”. The only difference between them is that with the copied source the Sparrow Framework source code is copied into your new project. If you choose linked, the Sparrow Framework source is connected to your new project through your SPARROW_SRC variable in Xcode.

Why 2 templates? Mainly because the Xcode template format is undocumented and I haven’t quite worked out how to include a linked project easily in a template. This means that you have to tweak a few things when you use a linked project unfortunately. But never fear! This post has a handy guide to getting it working a little further down.

Although it’s recommended that you use the template with the linked Sparrow source (because it’s a lot easier to update Sparrow-Framework that way), you may actually want to have a project with the Sparrow source copied. For example, if you are doing some hardcore hacking of the source this is a good option, or if you want to create a self contained project you can archive and mail to people it’s great for that too.

On with the guide!

Setting up linked source SparrowBones projects

Choose the right one:

Fill in some blanks and choose which device family to aim for. IMPORTANT: Uncheck “Use Automatic Reference Counting” (Sparrow doesn’t work with that yet). I also uncheck “Use Storyboard” because I haven’t learned how to use those:

Next, we have to fix that red Sparrow.xcodeproj reference. Select it and press Alt-Cmd-1 to show the inspector:

Then change it to be relative to your linked Sparrow Framework source. NOTE: the link name may be different for you – it depends on what you entered when setting it up (if you haven’t set a link to the source up, do that now before continuing):

If you look back at the Project navigator you should see Sparrow.xcodeproj as an expandable project:

This is important. If it doesn’t have the arrow, you will have to quit Xcode and then re-launch it and open the project. Sometimes Xcode is a bit slow about picking up path changes.

If that all important triangle is next to Sparrow.xcodeproj, you have one more thing to do. Xcode needs to know that it has to build Sparrow.xcodeproj as a dependency of your game target. Here’s how: 1) Select Sparrow.xcodeproj in the project navigator, 2) select your game target in the editor window, 3) go to the Build Phases section, 4) expand the target dependencies and click the plus.

In the window that appears, select the Sparrow target:

Select Add. If my instructions worked, you should now have Sparrow as a dependency:

That’s it! Simple once you know how. You should now be able to run the project in one of the simulator targets and you will some see Exciting Boxes on the screen. Awesome. Well done you!

A Note on Unit Tests

If you want to write unit tests, and I know you do, you will have to add all the Frameworks in the frameworks folder to your <AppName>Tests target, otherwise you will get lots of Mach-O linker errors: