Sparrow 1.3

Daniel Sperl on March 7, 2012

With all the buzz about Starling, our first-born bird has felt somewhat neglected during the last months. Actually, I think he was starting to get a little jealous of his new sister bird!

I must say I agree with him: Sparrow's last update was in the middle of last year, and much has changed in the iOS world since then! An update was long overdue.

But the waiting is over - Sparrow 1.3 is finished, and it's already waiting for you in the download section! And that's not all: if you're not completely blind, you will have already noticed that the bird has received a completely new outfit - shiny blue feathers and a whole new website!


In my regular visits in the Sparrow forum, I realized that there are a few topics that pop up constantly:

  • Automatic reference counting (ARC)
  • Autorotation of the game's content
  • Adding UIKit elements, like iAds or GameCenter
  • Creating universal applications

With the exception of ARC, all of that could already be done with Sparrow - but it was not obvious how to do it, because it required knowledge about Apple's UIKit libraries. And even if you knew those, it took a lot of trial and error to get it right.

Well, no longer! Sparrow's new Scaffold project makes all three of those tasks extremely simple. I'm going to describe these features in the rest of this article.

Automatic Reference Counting

With iOS 5, Apple introduced a simplified way to manage memory, called ARC (Automatic Reference Counting). It allows you to skip those "retain" and "release" calls; this is now the job of the compiler.

With this version, you can finally use Sparrow in ARC projects. Sparrow itself is still using the conventional mechanism, and is thus still compatible with iOS down to version 3.0; but it's perfectly fine to write your Sparrow game using ARC now. I can only recommend to any user to make use of this feature: you'll write less code and won't leak memory as easily. As a bonus, your games will even run faster.

To activate ARC in the scaffold project, just load it up and use Xcode's refactoring mechanism: Edit/Refactor/Convert to ARC. The same will most probably work in your existing games.

New Scaffold Project

The most important addition in Sparrow 1.3 is the new scaffold project. Once difficult tasks are now "piece of cake"! =)

The project contains more files than before, but don't worry: your game logic still starts in "Game.m", and that's probably all you'll have to look at. I will write detailed blog posts about how to achieve those common tasks soon; in the meantime, here is an overview that will get you started with the new scaffold.


Let's start with autorotation. To have your game rotate automatically when the user rotates his or her device, enter the Target settings of the project in Xcode and select the supported orientations in the 'Summary' tab.

If you just want to support one set of orientations (either both portrait or both landscape), you're already done. Yep, that's all you have to do! The game will rotate correctly.

If you want to support all orientations, you'll still have to write some code, of course, but Sparrow takes care of the basics. It dispatches an event with the type SP_EVENT_TYPE_RESIZE in which you can then move your objects to different positions.

[self addEventListener:@selector(onResize:) atObject:self forType:SP_EVENT_TYPE_RESIZE];

- (void)onResize:(SPResizeEvent *)event
    NSLog(@"new screen width:  %f", event.width);
    NSLog(@"new screen height: %f", event.height);
    NSLog(@"is Portrait?       %d", event.isPortrait);

The screen is automatically rotated in a smooth animation; you're responsible for moving your objects to the correct position, depending on the current screen size.

Adding UIKit elements

The most difficult part about screen rotations has always been a peculiarity of OpenGL content. You should not rotate an UIView containing OpenGL content (like Sparrow's SPView), because that is bad for the performance (at least on older devices). That's why I always recommended to rotate the Sparrow content instead.

That works fine until you want to display non-Sparrow content, like iAds or AlertBoxes. They didn't recognize the rotation change and showed up in the wrong rotation.

For that reason, the scaffold defines an "SPOverlayView" that is placed directly above Sparrow and is always rotated correctly. Add your UIKit content to that view, and you're settled!

Creating Universal Apps

When you create a universal application with HD textures ("@2x" suffix), the game looks gorgeous on the iPhone 4. But on the 1st and 2nd iPad generations, the "@2x" textures are not loaded: those devices don't have a retina display, after all.

But still: the "640x960" resolution of the iPhone is not that much smaller than the "768x1024" pixels of the iPad. Thus, it would make sense to use those HD textures on the iPad, too.

In fact, if we could treat the iPad just like a retina version of a device with a resolution of 384x512 (half the iPad resolution), it would be very simple to create a universal app. We'd just have to move our objects to a slightly different position, depending on the device (320x480 is only a little smaller than 384x512). Just like the Retina iPhone, the iPad would load "@2x" textures, using the full 768x1024 resolution.

That's exactly how it's done in Sparrow 1.3! Just call the following method to activate this feature:

[SPStage setSupportHighResolutions:YES doubleOnPad:YES];

The AppScaffold is already configured in that way. It is, per default, a universal app now. I recommend you start it up on an iPhone and an iPad. Both work out of the box, without any device-dependent code in the game.

And since rumors have it that today's presentation of the iPad 3 will reveal a retina display with the unbelievable dimensions of 1536x2048 pixels, you'll be glad to hear that this approach is iPad3-compatible already: in the above configuration (doubleOnPad:YES), Sparrow will load "@4x" textures on that device! I think that's a first of all gaming frameworks out there. ;-)

(Naturally, if you don't activate this feature, the retina iPad will use "@2x", just like before. This feature is just a handy alternative to create Universal Apps.)

Other changes

That's a mouthful already -- but it doesn't stop there! Here are other noteworthy features of Sparrow 1.3. As always, the full list is available in the changelog on GitHub.

  • added support for device modifiers (~iphone, ~ipad) in image filenames
  • added BareBone project, which replaces the old app scaffold
  • added support for new PVR texture types: I8, A8, AI88, RGB888
  • added sortChildren method to SPDisplayObjectContainer
  • added currentTime property to SPTween
  • added fadeTo method to SPTween
  • added broadcastEvent method to SPDisplayObject
  • added setIndex:ofChild: method to SPDisplayObjectContainer
  • added 'SP_SWAP' macro
  • added 'SP_CLAMP' macro
  • added more utility methods to point, rectangle and matrix classes

Final Words

Our small blue bird doesn't need to be jealous any longer, does he? I hope you like the new release and feel the same way! =)