How to create a Sparrow Project from Scratch

Daniel Sperl on November 17, 2010

Sometimes, you want to use Sparrow without having the option to use the app scaffold or the Xcode template. This can happen e.g. when you want to integrate Sparrow into an existing project. This is a topic that pops up regularly in the forum.

That's why I wrote this tutorial. Don't worry, it's not difficult - most of the steps have to be followed in any non-trivial iPhone application. However, there are some things that many of us are not accustomed to - like using Xcode's source tree variables.

This tutorial starts from scratch. When you follow it step by step, the outcome will be a project just like the app scaffold that's part of Sparrow. Good luck!

UPDATE: The information in this blog post is outdated. An updated version of the steps you have to take can be found in the Sparrow Wiki: Xcode3, Xcode4.

1. Set up the Sparrow project reference

  • Create a new "Window-based" iPhone Application
  • Open your project in Xcode.
  • In the “Groups & Files” pane of Xcode, add the Sparrow project (Sparrow.xcodeproj) by selecting the project root and hitting Option+Cmd+A (add to project)
  • When the “Add to Project” dialog is displayed, use the following settings:
  • Copy items (...): no
  • Reference Type: Relative to SPARROW_SRC
  • Text Encoding: UTF-8
  • Recursively create groups for any added folders: yes

2. Configure the Library Dependencies, Linking, and Header Files

  • Click on "Project - Edit Project Settings". Click on the build tab and scroll down to the "Search Paths" section.
  • Set "User Header Search Paths" to: ${SPARROW_SRC}, recursive: yes
  • Still in the Build-settings, under "Other Linker Flags" add: -ObjC and -all_load
  • Click on "Project - Edit Active Target". Then select the general tab and add Sparrow to the "Direct Dependencies".
  • In the same Window, under "Linked Libraries", add "AudioToolbox.framework", "AVFoundation.framework", "OpenAL.framework", "OpenGLES.framework", and "QuartzCore.framework"
  • Finally, click and drag "libSparrow.a" from underneath the cross-project reference to “Targets - [your target] - Link Binary with Libraries.”

3. Create the base Source Classes

Create Game.h:

#import <Foundation/Foundation.h>
#import "Sparrow.h"

@interface Game : SPStage


Create Game.m:

#import "Game.h"

@implementation Game

- (id)initWithWidth:(float)width height:(float)height
    if (self = [super initWithWidth:width height:height])
        // 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;

Modify ProjectAppDelegate.h:

#import <UIKit/UIKit.h>
#import "Sparrow.h"

@interface ProjectAppDelegate : NSObject <UIApplicationDelegate>
    UIWindow *window;
    SPView *sparrowView;

@property (nonatomic, retain) IBOutlet UIWindow *window;
@property (nonatomic, retain) IBOutlet SPView *sparrowView;


Modify ProjectAppDelegate.m:

#import "ProjectAppDelegate.h"
#import "Game.h"

@implementation ProjectAppDelegate

@synthesize window;
@synthesize sparrowView;

- (void)applicationDidFinishLaunching:(UIApplication *)application 
    [SPStage setSupportHighResolutions:YES];
    [SPAudioEngine start];
    Game *game = [[Game alloc] init];        
    sparrowView.stage = game;
    [game release];
    [window makeKeyAndVisible];
    [sparrowView start];

- (void)applicationWillResignActive:(UIApplication *)application 
    [sparrowView stop];

- (void)applicationDidBecomeActive:(UIApplication *)application 
    [sparrowView start];

- (void)dealloc 
    [sparrowView release];
    [window release];
    [super dealloc];

4. Create a Sparrow View

  • Open "MainWindow.xib" in the interface builder
  • Drag a "UIView" into the main application window
  • In the properties of the View, set the class manually to "SPView" (topmost entry in the rightmost tab).
  • If you need support for multitouch, activate it in the leftmost tab
  • Make a connection to the sparrowView-property of the Application Delegate (in the connections-tab of the Application Delegate, drag a line from the sparrowView-property to the new view).
  • Save the file and quit interface builder.

5. Phew! Done! (Hopefully)

If everything works, you should see a window with a red square. Congratulations!