EDIT:
Please note I am no longer managing this code. It has moved here: https://github.com/cocos2d/cocos2d-iphone-extensions/tree/master/Extensions/CCScrollLayer

I must have spent over a week coming up with a good solution for this. The effect I was after was a scrollable menu for my game, similar to Angry Birds where the user can flip between levels but also see a preview of the previous/next page on either end of the screen. I came across Nate Murray’s excellent UIScrollView solution but it wasn’t quite what I was looking for and using UIScrollView seemed like too much of an overhead. I needed something simple, preferably wrapped up in a single class.

After searching various community forums I finally came across DK101′s solution which was exactly what I was looking for. A simple CCLayer subclass that would allow me to create an array of CCLayers then add whatever I wanted to it then add the whole lot to my scene. Simple. You are able to add anything you can add to a CCLayer – so a label, menu, image etc. It will all work nicely.

I ended up making a few modifications to it like updating it to work with Cocos2d 0.99.5 and adding the option to set the width of the screens for the Angry Birds style preview effect. There was also an issue with the touch delegate on subsequent scenes. I have put my changes up on Github. Here’s a sample:

To use it in your project:

1. add both files to your project
2. in your scene import CCScrollLayer.h
3. in your scene’s init method construct each layer and pass it to the CCScrollLayer class:

e.g.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

// get screen size
CGSize screenSize = [CCDirector sharedDirector].winSize;
 
/////////////////////////////////////////////////
// PAGE 1
////////////////////////////////////////////////
// create a blank layer for page 1
CCLayer *pageOne = [[CCLayer alloc] init];
 
// create a label for page 1
CCLabelTTF *label = [CCLabelTTF labelWithString:@"Page 1" fontName:@"Arial Rounded MT Bold" fontSize:44];
label.position =  ccp( screenSize.width /2 , screenSize.height/2 );
 
// add label to page 1 layer
[pageOne addChild:label];
 
/////////////////////////////////////////////////
// PAGE 2
////////////////////////////////////////////////
// create a blank layer for page 2
CCLayer *pageTwo = [[CCLayer alloc] init];
 
// create a custom font menu for page 2
CCLabelBMFont *tlabel = [CCLabelBMFont labelWithString:@"Page 2" fntFile:@"customfont.fnt"];
CCMenuItemLabel *titem = [CCMenuItemLabel itemWithLabel:tlabel target:self selector:@selector(testCallback:)];
CCMenu *menu = [CCMenu menuWithItems: titem, nil];
menu.position = ccp(screenSize.width/2, screenSize.height/2);
 
// add menu to page 2
[pageTwo addChild:menu];
////////////////////////////////////////////////
 
// now create the scroller and pass-in the pages (set widthOffset to 0 for fullscreen pages)
CCScrollLayer *scroller = [[CCScrollLayer alloc] initWithLayers:[NSMutableArray arrayWithObjects: pageOne,pageTwo,pageThree,nil] widthOffset: 230];
 
// finally add the scroller to your scene
[self addChild:scroller];

Download the source

And a MASSIVE thank you to DK101

This example assumes you know your way around an XCode project and know the basics of Objective-C and Cocos2d. If not, there are plenty of good tutorials around. See my previous post for some useful links. Also, I’m using Cocos2d 0.99.5 so some of this syntax may not work on older versions.

Now, onto the tutorial:

The first thing you want to do is get yourself a sprite sheet and associated plist file. Cocos2d has a bunch of these in its examples folder but you can also make your own using the excellent Zwoptex app. The app will let you add a bunch of images and it will then re-arrange them, export a single image and also generate a plist file containing all the coordinates. This means you won’t have to mess around with x/y pixels to get everything lined up.

Important: make sure in the Zwoptex publish settings you select Cocos2d for the coordinates format.

Once you have added the two files to your project, you can load all the individual frames in the cache and use them however you like.

1
2

// load the plist file into the frame cache
[[CCSpriteFrameCache sharedSpriteFrameCache] addSpriteFramesWithFile:@"mysprite.plist"];

That’s it. Zwoptex will give each frame its own name. Look inside the plist file to see what they are called. These will most likely be the original file names of the images before you combined them into one.

Now that the frames are in the cache, we can create and display them as individual sprites like this

1
2

CCSprite *sprite = [CCSprite spriteWithSpriteFrameName:@"dude1.png"];
[self addChild: sprite];

You can add any of the other frames to the scene the same way, just make sure you use the correct frame name like dude2.png, dude3.png etc. Again, if you’re not sure what the names are, just open the plist and look at the frames node.

Now that we have all our frames ready to use, we can do some cool things with it like animate them or use them as rollover effects for menu buttons. In the game I’m currently developing I wanted the character to blink from time to time. So I used two sprite images, one with the character’s eyes open and one with its eyes shut. You can then create a sequence and animate them like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

// Load sprite plist file
[[CCSpriteFrameCache sharedSpriteFrameCache] addSpriteFramesWithFile:@"dude_blinking.plist"];
 
// Create a blank array to store all the frames	
NSMutableArray *blinkAnimFrames = [NSMutableArray array];
 
// Add the frames 3 times. One with eyes open, one shut and one open again	
[blinkAnimFrames addObject: [[CCSpriteFrameCache sharedSpriteFrameCache] spriteFrameByName:[NSString stringWithFormat:@"dude_open.png"]]];
[blinkAnimFrames addObject: [[CCSpriteFrameCache sharedSpriteFrameCache] spriteFrameByName:[NSString stringWithFormat:@"dude_shut.png"]]];
[blinkAnimFrames addObject: [[CCSpriteFrameCache sharedSpriteFrameCache] spriteFrameByName:[NSString stringWithFormat:@"dude_open.png"]]];
 
// Create a 3-frame animation using the array and use 0.2 seconds delay between each frame	
CCAnimation *blinkanimation = [CCAnimation animationWithName:@"blinker" frames:blinkAnimFrames];
CCAnimate *blink = [CCAnimate actionWithDuration:0.2f animation:animation restoreOriginalFrame:NO];
 
// Now create the blinking action sequence	
CCAction *blinkAction = [CCRepeatForever actionWithAction:
    [CCSequence actions:
        [CCDelayTime actionWithDuration:2.0f],
        blink,
        [CCDelayTime actionWithDuration:3.0f],
        blink,
        [CCDelayTime actionWithDuration:0.2f],
        blink,
        [CCDelayTime actionWithDuration:2.0f],
    nil]
];
 
// Add the actual sprite (first frame from cache) to the scene
CCSprite *dude = [CCSprite spriteWithSpriteFrameName:@"dude_open.png"];
[self addChild: dude];
 
// Finally, run the blinking animation
[dude runAction: blinkAction];

If you study the blinkAction carefully, you’ll see we have just created an endless loop that runs the 3-frame blink action with some pauses in the middle. The sequence is:

(start loop)
1 – Pause for 2 seconds
2 – Blink
3 – Pause for 3 seconds
4 – Blink
5 – Pause for 0.2 seconds
6 – Blink
7 – Pause for 2 seconds
(end loop)

This gives us a semi-realistic blinking animation like this:

Have fun!

Cocos2d on the other hand is open source and has a pretty big community of developers so it’s relatively easy to get help by searching or posting questions on its dev forums. It is a pretty mature and flexible framework that comes with a bunch of templates and libraries including Box2D and Chipmunk physics engines. It’s a proven framework since there are hundreds of games in the app store that were developed using Cocos2d. Trainyard, for example, was made entirely with Cocos2d and you probably know it’s one of the most popular games in the app store at the moment.

It is, however, all in Objective-C and in my opinion a pretty steep learning curve if you don’t know the language. There are alternatives as mentioned before but if you’re planning to seriously build games as well as apps for iOS you probably should try and learn Objective-C now.

The Cocos2d documentation isn’t fantastic so I’ve had to learn it slowly by looking at tutorials and code samples. Objective-C is an alien world to me so it’s like learning 2 languages at once. But once you get your head around it, it’s actually a lot of fun. I’m going to try and post a few tutorials on my blog from time to time but if you decide to sit down and learn Objective-C and Cocos2d, you may want to start here:

1. Objetive-C for Absolute Beginners (book)
2. The New Boston Objective-C tutorial screencasts
3. The New Boston Cocos2d tutorial screencasts
4. Ray Wenderlich’s Cocos2d game tutorial (more on his site)

So I set out to create an app for the iPhone with Objective-C. My app is pretty simple. It basically pulls in RSS news, audio podcast and video podcast feeds into a UITableView list, allowing the user to read, listen and watch news stories from the Democracy Now! website.

I managed to put together the app pretty quickly but I ran into a lot of issues when I tried to parse and massage the XML data. For starters, cocoa does not have native support for regular expressions (but there are several external libraries). I wanted to clean up the content I was getting back before displaying it to the user but I soon realised something that would normally take me a few minutes in Python/PHP/Javascript would take a lot longer in Objective-C. Parsing XML using NSXMLParser was an absolute nightmare and extremely slow. I rarely work with XML these days and find JSON a much easier protocol to deal with. I even tested the app with some sample JSON data using the excellent json-framework libarary and it was much easier and faster. Alas, I only had RSS feeds to work with.

The other problem I ran into was slow HTTP requests. It would sometimes take up to 20 seconds just to load the first screen. This was due to a combination of slow connection speeds, long response times from the data provider and a slow XML parser.

The solution I came up with was to do as little as possible in the phone app as far as the data was concerned. I decided to use Google App Engine to fetch the data from the source, parse, rejig, massage and beautify in Python, then serialise and return the results in JSON to the phone app to use.

It may sound like this would increase response times even more since the phone would have to first call GAE, then GAE would need to call the data source and then all the way back to the phone. This is true, however, once the data is with GAE we have the luxury of using memcache and datastore. The RSS and podcast feeds are updated once a day so there’s no reason to request the data from the source every time the user loads the app. Because each time we have to make the HTTP call, parse the data and load it up. This is extremely slow and unnecessary. We can just make one request a day, then parse, cleanup and cache the results for the next user that requests it.

So the app only talks to GAE. GAE first checks memcache to see if we have a cached version. If we don’t, it will make the HTTP call, fetch the data, parse, serialise, cache and return results. If we do have a cached version, there’s nothing else to do but to return the data. A cron job will also run every 24 hours to make sure memcache is up to date.

If you really want a solid and reliable app, you need to think about all the edge cases also. What happens if the cache expires and the data provider’s website is down? At that exact moment a user loads the app only to get an error message saying there’s nothing to show. An unlikely scenario but not impossible. So the way I got around this issue was to store the serialised JSON output in GAE’s datastore as well. We always use the data from memcache but should memcache be empty and the data source down, we can switch over to the datastore and load yesterday’s content instead. Not ideal but better than having a broken app.

This is a bit of an overkill for such a simple app but it’s super fast and efficient and will work well for almost any app that relies on 3rd-party APIs. To be fair, it was my lack of experience with Objective-C that led me to using GAE. I feel much more comfortable in Python than Objective-C and I’m sure an experienced cocoa developer would have no problems parsing and massaging data in the app itself.

Of course there is one other edge case – Google App Engine could go down or worst, the interwebz could break. In which case, a simple error message will suffice.

You can download Democracy Now! app on iTunes

KALX app on iTunes

Update, 28 Sep 2010: I have just added multitasking support to this app. You can now listen to the audio in the background while you quit and use other apps.