Sparrow 2.0 FAQ

Daniel

I'm moving Brian's great FAQ thread into a new one, with one post per question. The old thread has been filled with too many other topics by now.

What follows is a list of questions and answers about the changes and possible pitfalls of Sparrow 2.0. If anyone wants to add additional information, feel free to add a post.

But please do not use this thread for any discussions!
Thanks!

Daniel

Q: Why doesn't self.stage or [SPStage mainStage] work?

In Sparrow 2.0, there is a new and improved way to access the stage through the new SparrowClass. Here's how it works.

// access the stage
SPStage *stage = Sparrow.stage;

// access the juggler
SPJuggler *juggler = Sparrow.juggler;

// access the view controller (for adding UIKit content)
SPViewController *viewController = Sparrow.currentController;

// the scale factor can also be accessed through the SparrowClass
float scaleFactor = Sparrow.contentScaleFactor;

Daniel

Q: I heard the fancy UIKit handling from the 1.x scaffold is now baked into the core. How does it work?

The 1.x scaffold made it very simple to use UIKit components along with your Sparrow content. Now, this functionality is available and has even improved! Now you don't have to deal with passing events and data in sometimes confusing ways. Here is an example of how I would add a UISwitch to my game (based on the 1.x example from the wiki).

- (void)addSwitch {
    // create the switch (there is a _switch instance variable)
    _switch = [[UISwitch alloc] initWithFrame:CGRectMake(15, 15, 0, 0)];

    // add an event for when the switch value changes (on or off)
    [_switch addTarget:self action:@selector(onSwitchValueChanged)
             forControlEvents:UIControlEventValueChanged];

    // add the switch to the view
    [Sparrow.currentController.view addSubview:_switch];
}

- (void)onSwitchValueChanged {
    // log the new switch state
    NSLog(@"switch state: %@", (_switch.isOn ? @"ON" : @"OFF"));
}

Daniel

Q: I don't see the frame rate option in the new initialization process. How can I specify a frame rate?

First of all, Sparrow now defaults to 30 FPS. Only change this if you want to bump it up to, for example, 60 FPS. Since Sparrow's SPViewController is now a GLKViewController (GLKit) subclass, you can use the properties on it just as you would normally when you initialize Sparrow. One of these properties is "preferredFramesPerSecond". Here is the scaffold project's App Delegate "application: didFinishLaunchingWithOptions:" method with frame rate specified.

- (BOOL)application:(UIApplication *)application
        didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    NSSetUncaughtExceptionHandler(&onUncaughtException);

    CGRect screenBounds = [UIScreen mainScreen].bounds;
    _window = [[UIWindow alloc] initWithFrame:screenBounds];

    _viewController = [[SPViewController alloc] init];

    // set the frame rate
    _viewController.preferredFramesPerSecond = 60;

    [_viewController startWithRoot:[Game class] supportHighResolutions:YES
                                                doubleOnPad:YES];

    [_window setRootViewController:_viewController];
    [_window makeKeyAndVisible];

    return YES;
}

Daniel

Q: I was using tween delays and times to chain tweens together, but now the time property is gone. How can I do this now?

In 2.0, to move the API closer to Starling's as well as for consistency, the time property of SPTween has been deprecated in favor of totalTime.

// used for chaining tweens together (making one run immediately after another)
tween2.delay = tween1.totalTime;
tween3.delay = tween2.totalTime + tween2.delay;

Daniel

Q: I was using SPTween's events to handle completion, start, updates, etc. Where did those events go?

One of the coolest new additions to Sparrow is block based event listening. As well as being able to use events like SP_EVENT_TYPE_TOUCH and ENTER_FRAME in blocks, tweens have dedicated block properties. You can still separate your event code into a separate function if you choose. Most importantly, if Xcode warns you about capturing a variable in a block, heed its advice and create a weak variable version.

- (void)startTweens {
    // create a tween and set its animation
    SPTween *tween1 = [SPTween tweenWithTarget:object1 time:3];
    [tween1 animateProperty:@"x" targetValue:100];

    // here's the magic
    tween1.onComplete = ^() {
        [object1 removeFromParent];
    };

    // add it to the juggler
    [Sparrow.juggler addObject:tween1];

    // create another tween and set its animation
    SPTween *tween2 = [SPTween tweenWithTarget:object2 time:3];
    [tween2 animateProperty:@"y" targetValue:100];

    // created a weak tween2 variable because Xcode warned me about it being captured in the block
    __weak SPTween *tween2weak = tween2;
    tween2.onComplete = ^() {
        // this time I pass the tween to a separate function that handles the event
        [self onTween2Complete:tween2weak];
    };

    // add the second tween to the juggler
    [Sparrow.juggler addObject:tween2];
}

- (void)onTween2Complete:(SPTween *)tween {
    // Grab the object from the tween's target property and do something with it
    SPDisplayObject *object2 = tween.target;
    [object2 removeFromParent];
}

Daniel

Q: What happened to 'SPCompiledSprite'? I can't find it any longer.

You no longer need to use a special class to compile sprites. This functionality is now part of the normal 'SPSprite' class. Use the 'flatten' method to optimize the object; 'unflatten' to make the sprite behave just like before.

SPSprite *sprite = [SPSprite sprite];
[sprite addChild:...]; // add some content

[sprite flatten]; // now it's optimized
[sprite unflatten]; // now it's just a normal sprite again.

Daniel

Q: Some of my PNG textures can't be loaded; I get some obscure error code "12". It worked fine with the old version, though!

Sparrow now uses Apple's GLKTextureLoader class to load images. While this has several advantages (e.g. async texture loading), it has the downside that this class is a little picky when it comes to PNG images. Some image processors save your PNGs with 16 bits per pixel, and those can't be loaded. Using the command line tool "convert" (part of ImageMagick), you can easily fix those files:

convert -define png:bit-depth=8 input.png output.png

UPDATE: Sparrow 2.1 got rid of "GLKTextureLoader", because it caused a lot of problems (beside the one mentioned here). So this error shouldn't pop up any longer!

Daniel

Q: I create a custom hit test for a class of mine; for some reason, it doesn't work any longer!

The definition of the 'hitTestPoint:' method has been simplified. The 'forTouch:' parameter has been removed -- I don't think it was ever called for something else than touches, anyway. Set up your hit tests like this now:

- (SPDisplayObject*)hitTestPoint:(SPPoint*)localPoint
{
    if (!self.visible || !self.touchable)
        return nil; 

    // add your custom hit test code here.
}

Daniel

Q: The old version of the particle system is not compatible with Sparrow 2.0. Where can I find an updated version?

Here you are: https://github.com/Gamua/Sparrow-Extension-Particle-System