How to create a Sparrow Project from Scratch

This tutorials shows you how to get from a brand-new, empty Xcode project to a Sparrow-powered scaffold. It requires at least Sparrow 2.1 and Xcode 5.

Create a new Xcode Project

Via “File - New - Project”, create a new “Empty Application” for iOS, and save it to a path of your choice.

Beginning with Xcode 6, you can use either Objective-C or Swift as programming language for your Game. Sparrow supports both. The set-up procedure is almost the same; this guide will help you with both languages.

Add the Sparrow Framework

Now we are ready to add Sparrow to our project. Beginning with Sparrow 2.1, there are two different ways to do that.

Beware: if you want to use Swift, you must use the “Source Tree Variable” approach. The framework method does not work with Swift (yet).

Via "Sparrow.framework" file

Beginning with Sparrow 2.1, a “Sparrow.framework” file will be available in the Sparrow download package. If you don't find such a file, just open up the Sparrow project, select an actual “iOS device” as compile destination and then hit “Project - Archive”. The framework will be compiled into “sparrow/build”.

In your new project, first click on the project name in the “Project Navigator”. Then select your main compilation target and enter the “Build Phases” tab. Open up the section “Link Binary With Libraries” and click on the “+”. A new window will pop up; click on the button labeled “Add Other …”. Find the “Sparrow.framework” file and select it in the file chooser.

The advantage of this solution is that it's very easy to set-up. The downside: you can't peek into / modify the Sparrow source while you're working on your game.

Via "Source Tree Variable"

  1. If this is your first Sparrow project, set up the “Source Tree Variables” in Xcode as shown here.
  2. In the “Project Navigator” pane of Xcode, add the Sparrow project (Sparrow.xcodeproj) by selecting the project root and hitting Option+Cmd+A (add to project). Choose the following settings in the file dialog:
    • Copy items (…): no
    • Folders: Create Groups for any added folders
    • Add to Target: (choose your target)
  3. Click on the Sparrow project in the “Project Navigator” and open up the File Inspector (⌥⌘1).
  4. In the “Location” drop-down menu, choose: Relative to SPARROW_SRC

This solution is a little more work to set-up; in exchange, you can easily look into the Sparrow source anytime.

Add required Frameworks

Click on the project name in the navigator on the left to show the project settings. Click on the “Build Phases” tab and add the following additional frameworks in “Link Binary With Libraries”:

  • AudioToolbox.framework
  • AVFoundation.framework
  • GLKit.framework
  • OpenAL.framework
  • OpenGLES.framework
  • QuartzCore.framework
  • libz.dylib
  • libSparrow.a

Modify the Source Code


In “Supporting Files / [Project-Name]-Prefix.pch”, add the Sparrow import statement.

#ifdef __OBJC__
    #import <UIKit/UIKit.h>
    #import <Foundation/Foundation.h>
    #import <Sparrow/Sparrow.h>  // <== HERE

Then create a new class called “Game” with the following contents:

@interface Game : SPSprite
#import "Game.h" 
@implementation Game
- (id)init
    if ((self = [super init]))
        // This is where the code of your game will start;
        // in this sample, we add just a simple quad to see if it works.
        SPQuad *quad = [SPQuad quadWithWidth:100 height:100];
        quad.color = 0xff0000;
        quad.x = 50;
        quad.y = 50;
        [self addChild:quad];
    return self;

In “AppDelegate.m”, import that class and add two member variables.

#import "Game.h"
@implementation AppDelegate
    SPViewController *_viewController;
    UIWindow *_window;

Furthermore, overwrite the “application:didFinishLaunchingWithOptions:” method like this:

- (BOOL)application:(UIApplication *)application 
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
    CGRect screenBounds = [UIScreen mainScreen].bounds;
    _window = [[UIWindow alloc] initWithFrame:screenBounds];
    _viewController = [[SPViewController alloc] init];
    // Enable some common settings here:
    // _viewController.showStats = YES;
    // _viewController.multitouchEnabled = YES;
    // _viewController.preferredFramesPerSecond = 60;
    [_viewController startWithRoot:[Game class] supportHighResolutions:YES doubleOnPad:YES];
    [_window setRootViewController:_viewController];
    [_window makeKeyAndVisible];
    return YES;


In order to be able to access Sparrow from Swift, we first need to set up a so-called “bridging header”. Create such a file with the following contents:

// Use this file to import those Objective-C files that you would like to expose to Swift.
#import <Sparrow/Sparrow.h>

Xcode needs to find this header, of course. In the “Build Settings” of your project, add find the setting “Objective-C Bridging Header” and add the following contents:


(The actual path depends on your project setup.)

With this out of the way, we can now use all Sparrow classes from Swift. Let's start with our root Sparrow class, called “Game”.

import Foundation
class Game : SPSprite {
    init() {
        var quad = SPQuad(width: 100, height: 100, color: SPColorRed)
        quad.x = 50
        quad.y = 50

Now we just have to make sure that Sparrow starts up! To do that, modify “AppDelegate.swift”. We're changing the member variables and the application method.

import UIKit
class AppDelegate: UIResponder, UIApplicationDelegate {
    var _window: UIWindow!
    var _viewController: SPViewController!
    func application(application: UIApplication, didFinishLaunchingWithOptions launchOptions: NSDictionary?) -> Bool {
        _viewController = SPViewController()
        _viewController.showStats = true
        _viewController.multitouchEnabled = true
        _viewController.preferredFramesPerSecond = 60
        _viewController.startWithRoot(Game.self, supportHighResolutions: true, doubleOnPad: true)
        _window = UIWindow(frame: UIScreen.mainScreen().bounds)
        _window.rootViewController = _viewController
        return true
    // ...

My Beta-Version of Xcode did not find Sparrow at this point — but the errors disappeared after I cleaned the project (Shift+Cmd+K).

Still, I received the following linker warning:

  directory not found for option 

If the same happens to you, remove that path from the “Library Search Paths” in the target's “Build Settings”.

Phew! Done! (Hopefully)

If everything works, you should be able to launch the new project. You'll see the iPhone simulator with a red square on its screen. Congratulations!

  tutorials/creating_a_sparrow_project_from_scratch.txt · Last modified: 2014/07/07 13:10 by daniel
Powered by DokuWiki