The book, Cocos2d for iPhone 0.99 Beginner's Guide by Pablo Ruiz, is an introduction to game development using the cocos2d for iPhone framework (http://www.cocos2d-iphone.org/). cocos2d for iPhone is an open source game development framework for Objective-C based on the cocos2d framework originally written in Python. As the 2d in the title suggests, it is really geared towards 2D games, although there can be 3D effects. The framework is free to use even in commercial products and is actively maintained with a large community. The framework has even branched out towards iPad and Mac OS X development.

The book presents the cocos2d framework by walking the reader through building three different games: Coloured Stones (Bejeweled-like game), AerialGun (vertical shooter), and Totem Balance (physics puzzler). These games are presented through a series of steps, starting with installing cocos2d on through developing nearly complete games. Each of the steps are fairly small and the author doesn't present too many concepts in each step. However each step provides a concrete result so that the reader can quickly see the results of what was just added to the code. For example, one of the first steps in AerialGun simply displays the main player sprite. Then it quickly moves on to adding the enemy sprites and making them move and shoot. From there, steps are added to handle the accelerometer to steer the player sprite, shoot bullets from the player sprite, and handle collisions between sprites.

While none of these games are overly complex - there are probably hundreds in the app store like them - these games do hit the main concepts of cocos2d as well as provide an introduction to game development concepts. There are topics on touch/accelerometer handling, sprites, collisions, animations, scoreboards/huds, tile maps, menus, transitions, particles and physics. The author even adds the little extra "flash" to the games, especially in the Coloured Stones example. These include animating the appearance and disappearance of the stones, animating the background on major events, and animating score for the removed stones. While this does extend out the example a bit, it is nice that the author shows that adding effects like these are really simple to do in cocos2d yet add tremendous value visually.

In addition to just describing cocos2d, the author adds some game development insights along the way especially with respect to game performance such as sprite reuse, tiling backgrounds, avoiding large images, image and sound loading, and tips on using the physics engine. He also provides a brief tutorial on several common game development tools used to create tile maps and particle effects. At the end there is even a chapter on integrating OpenFeint, one of the more popular social networks for games.

My Thoughts

Full disclosure: I was sent a copy of this book to review by the publisher. However, this fact has no bearing on my review.

This book is geared towards beginners in cocos2d and to some extent game development. The author assumes the reader has basic knowledge of iPhone development and Objective-C. While a reader can start iPhone game development with this book, not having any other background in iPhone development will be an issue. If keywords like @selector, retain, and autorelease are not familiar to the reader, a good Objective-C and/or iPhone development book will be handy to have nearby.

In addition, while it touches on some concepts of game development as its primary purpose is cocos2d and so it does not provide information on items like artificial intelligence, multi-player, networking, and general game design. Another book or online resource is needed for these and other advanced topics.

As mentioned in the book summary above, the author does provide that extra little bit of detail on some of the examples to add some polish. However, I wish the book editing went through the same level of detail. There are numerous errors throughout, both in the code examples and the surrounding text, that detract from the overall book. These may confuse the reader, especially if they are truly beginners.

The other issue, which is common with all technical books detailing an active framework, is keeping up with the latest version of the cocos2d library (currently version 0.99.5, but 1.0 is on its way). For example, the book mentions the PVR textures can only be used for 2 or 4 bit textures, but the 0.99.5 release allows you to pack any type of texture in the PVR format for image loading speed gains.

As an experienced iPhone developer, with some previous exposure to cocos2d in the past, I found the book to be a good refresher on cocos2d basics. I did find the book really useful in its explanation of the more advanced topics like particle effects, node actions, and the Chipmunk physics engine. There were times I wish the book went into more details, but then again this book is a "beginner's guide" so that is expected.

Overall, I think this book is a good starting point for someone who wants to come up to speed on cocos2d. While a lot of information is available on the web, having all the information in one spot and presented in a consistent manner is very useful. That being said, unless the book is updated for the newer releases, the book will need to be used in conjunction with the latest API documentation on the website.

You can download the sample project from here, but the screenshots below show the transition in progress. Since Core Animation is focused around CALayers, my example creates to simple layers, one brown and one green, to transition between. The bottom scroll bar determines the amount of scaling that happens during the flip from one side to another - a positive setting makes it pop out towards the user. Setting this to 1.0 means the effect is just rotation around the y-axis (think of a playing card flipping from right to left around the middle), while a smaller number makes the side shrink during the flip. Click on one of the images to see the full application.

Now onto the code!

I started the example with a "View Based Application" iPhone template. First things first, be sure to QuartzCore.framework into your project to avoid build issues. The second thing to do is to include the QuartzCore header into any file that deals with Core Animation. In the example, this would be at the top of your ViewController.m file.

#import <QuartzCore/QuartzCore.h>

For this example, I create the two layers in the viewDidLoad function. I've rounded the corners to make it look a little nicer.

- (void)viewDidLoad {
	[super viewDidLoad];

	isFlipped = NO;

	topLayer= [CALayer layer];
	topLayer.doubleSided = NO;
	topLayer.name = @"1";
	topLayer.frame = CGRectMake(0.0f, 0.0f, 125.0f,125.0f);
	topLayer.position = CGPointMake(160.0f, 240.0f);
	topLayer.backgroundColor = [[UIColor brownColor] CGColor];
	[topLayer setCornerRadius:8.0f];
	[topLayer setMasksToBounds:YES];

	bottomLayer = [CALayer layer];
	bottomLayer.doubleSided = NO;
	bottomLayer.name = @"2";
	bottomLayer.frame = CGRectMake(0.0f, 0.0f, 125.0f,125.0f);
	bottomLayer.position = CGPointMake(160.0f, 240.0f);
	bottomLayer.backgroundColor = [[UIColor greenColor] CGColor];
	[bottomLayer setCornerRadius:8.0f];
	[bottomLayer setMasksToBounds:YES];

        // FIX for flipping over an image
        // Assuming this is over a background UIImageView (optional for folks)
        UIImageView* v = [[UIImageView alloc] initWithImage:[UIImage imageNamed:@"Space-03.jpg"]];
        // add this as the root of the current view; you can do this in IB
        [self.view insertSubview:v atIndex:0];

        // now add the flipping layers to a different view, above the UI Image, but below the controls
        // defined in the XIB
        UIView* flipView = [[UIView alloc] initWithFrame:self.view.frame];
        [self.view insertSubview:flipView aboveSubview:v];
        [v release];

        // add bottom first; add to the NEW view, not self
	[flipView.layer addSublayer:bottomLayer];
	[flipView.layer addSublayer:topLayer];
        [flipView release];

        [self updateLabel];
}

Now that we have the two layers created, I set the Flip button to perform the animation.

- (IBAction) flip: (id) sender
{
	// if we currently transitioning, ignore any further taps on the button until we are done
	if (isTransitioning)
		return;
	// figure out which layer is the current visible one
	CALayer* top = topLayer;
	CALayer* bot = bottomLayer;

	if ( isFlipped ) {
		top = bottomLayer;
		bot = topLayer;
	}

	CAAnimation *topAnimation = [self flipAnimationWithDuration:1.0f forLayerBeginningOnTop:YES scaleFactor:self.slider.value];
	CAAnimation *bottomAnimation = [self flipAnimationWithDuration:1.0f forLayerBeginningOnTop:NO scaleFactor:self.slider.value];

	CGFloat zDistance = 1500.0f;
	CATransform3D perspective = CATransform3DIdentity;
	perspective.m34 = -1. / zDistance;
	top.transform = perspective;
	bot.transform = perspective;

	topAnimation.delegate = self;
	[CATransaction begin];
	[top addAnimation:topAnimation forKey:@"flip"];
	[bot addAnimation:bottomAnimation forKey:@"flip"];
	[CATransaction commit];
}

Where all the magic happens is in the flipAnimationWithDuration:forLayerBeginningOnTop:scaleFactor: function which creates the animation for the actual flip of the layer. If the scale is 1.0 then it skips the scaling part.

-(CAAnimation *)flipAnimationWithDuration:(NSTimeInterval)aDuration forLayerBeginningOnTop:(BOOL)beginsOnTop scaleFactor:(CGFloat)scaleFactor
{
	isTransitioning = YES;
	// Rotating halfway (pi radians) around the Y axis gives the appearance of flipping
	CABasicAnimation *flipAnimation = [CABasicAnimation animationWithKeyPath:@"transform.rotation.y"];
	CGFloat startValue = beginsOnTop ? 0.0f : M_PI;
	CGFloat endValue = beginsOnTop ? -M_PI : 0.0f;
	flipAnimation.fromValue = [NSNumber numberWithDouble:startValue];
	flipAnimation.toValue = [NSNumber numberWithDouble:endValue];

 	// Shrinking the view makes it seem to move away from us, for a more natural effect
	// Can also grow the view to make it move out of the screen
 	CABasicAnimation *shrinkAnimation = nil;
    	if (self.slider.value != 1.0f ) {
        	shrinkAnimation = [CABasicAnimation animationWithKeyPath:@"transform.scale"];
        	shrinkAnimation.toValue = [NSNumber numberWithFloat:scaleFactor];

        	// We only have to animate the shrink in one direction, then use autoreverse to "grow"
        	shrinkAnimation.duration = aDuration * 0.5;
        	shrinkAnimation.autoreverses = YES;
    	}

    	// Combine the flipping and shrinking into one smooth animation
    	CAAnimationGroup *animationGroup = [CAAnimationGroup animation];
    	animationGroup.animations = [NSArray arrayWithObjects:flipAnimation, shrinkAnimation, nil];

    	// As the edge gets closer to us, it appears to move faster. Simulate this in 2D with an easing function
    	animationGroup.timingFunction = [CAMediaTimingFunction functionWithName:kCAMediaTimingFunctionEaseInEaseOut];
	animationGroup.duration = aDuration;

	// this really means keep the state of the object at whatever the anim ends at
	// if you don't do this then it reverts back to the original state (e.g. brown layer)
    	animationGroup.fillMode = kCAFillModeForwards;
    	animationGroup.removedOnCompletion = NO;

	return animationGroup;
}

Now to reset the state at after the animation is complete use the following function:

-(void)animationDidStop:(CAAnimation *)animation finished:(BOOL)flag
{
	isFlipped = !isFlipped;
	isTransitioning = NO;
}

Feel free to reuse the source as you see fit. Note the flip: and flipAnimationWithDuration:forLayerBeginningOnTop:scaleFactor: functions were modified from Drew McCormack's blog post for NSViews for the Mac. He placed his code in the public domain.

Well as it turns out people love free stuff! I was quite surprised by the demand! I'm sure OpenFeint's marketing helped drive up the demand in addition to the free cost.

So for the 28 hours (approximately) that Kascade was given away, the final numbers are:

- Total downloaded: 36,142
- Peaked at #91 for all the Free Apps (US)
- Peaked at #52 on the Free Games category
- Peaked at #8 on the Free Games - Puzzle category
- Peaked at #8 on the Free Games - Family category

After Kascade returned to the normal $0.99 price, there was a definite uptick in sales. Still early to tell if the sales will continue to stay at a higher level or will eventually return to the pre-sale levels.

Overall, I am quite pleased with participating in their giveaway.

textview.scrollEnabled = NO;
NSString *contentsToAdd = @"some string";
NSInteger len = [contentsToAdd length];
NSRange cursorPosition = [self.textview selectedRange];
NSMutableString *tfContent = [[NSMutableString alloc] initWithString:[self.textview text]];

// insert the string or replace the selection
NSUInteger loc = cursorPosition.location;
if (cursorPosition.length == 0)
  [tfContent insertString:contentsToAdd atIndex:loc];
else
  [tfContent replaceCharactersInRange:cursorPosition withString:contentsToAdd];

// now update the text view
[self.text setText:tfContent];
cursorPosition.location = loc + len;
cursorPosition.length = 0;

// should move the cursor
textview.scrollEnabled = YES;
self.textview.selectedRange = cursorPosition;
[tf release];

This entry is part 1 of a series that provides a starting point for anyone using cocos2d. This post kicks things off with useful links and setting up your project.

Starting Links

In addition to the main cocos2d site, the following is a list of links that I found helpful in starting development:

• http://monoclestudios.com/cocos2d_whitepaper.html
• http://lethain.com/entry/2008/oct/03/notes-on-cocos2d-iphone-development/
• http://beta.letstalkiphone.com/2009/05/tic-tac-toe-in-cocos2d/
• Misc links including the ones above

All the links above refer to the older versions of cocos2d and so all the examples will have to be slightly modified (new in 0.9 is that all classes are now prefixed with CC).

Setting Up

The good news that as of 0.8.1, cocos2d provides XCode templates to start your own project. It installs three templates: basic cocos2d, cocos2d + Box2D, and cocos2d + Chipmunk. Box2D and Chipmunk are two different physics engines (Chipmunk was derived from an early version of Box2D). Box2D is C++ and Chipmunk is C.

Once you select the XCode template, you have a simple example application that runs in the simulator after a build.

One thing to note is that the template copies all the cocos2d files (and its dependencies) into your project directory. This will be problematic if you to update your cocos2d install like I will need to do (especially with the pre-beta) since I would need to recopy all the files again. That sounds painful so there should be a better/easier way... static libraries to the rescue!

Static Libraries

Doing some research on the web, these two links provided most of the relevant information to enable making cocos2d a static library.

• http://blog.stormyprods.com/2008/11/using-static-libraries-with-iphone-sdk.html
• http://www.clintharris.net/2009/iphone-app-shared-libraries/

The first link shows how to create static libraries and use them in XCode for the iPhone. I'm not sure about prior releases, but the 0.9 version comes with static libraries already included as targets in the XCode project file so this link wasn't as relevant for the setup side of things (although it is a great read).

However, it did point out that you would need a version for every device/simulator combination you want to work with. Not ideal. After reading the second article, there is a way to avoid that.

Before I get into that, you should remove the 'cocos2d sources' from your newly created project. Down in the Targets section, remove the 'cocos2d libraries'.

Right click on your main target and Get Info. On the General tab, remove the 'cocos2d libraries' reference from the Direct Dependencies as well as under the Linked Libraries section.

At this point, I followed Clint's steps (from the second article) - except I skipped his first one: Set up a shared build output directory that will be shared by all Xcode projects.

I didn't do this and everything seems to work fine since the referenced project will build based on your current settings. Of course, I just started my development with this so time will tell if I really needed it.

Once you get to the step called Configure the Library Dependencies, Linking, and Header Files, you just copy the subset of libraries from the cocos2d project reference. A good starting point for inclusion: cocos2d. Chipmunk (for physics), libpng, and CocosDenshion (for sound).

A Few Notes

In 0.9 libcocos2d.a actually includes FontLabel so you don't need to explicitly pull that in (if you do you will have an issue with a duplicate symbol).

You will need to make a single change in this version of cocos2d in order to get the libpng.a to work. Open the cocos2d project and for the libpng target, remove (uncheck) the pngtest.c from the libpng static library target. This file has a main which causes a duplicate symbol issue when compiled in with your application.

The integration was painless. After registering on their site, I followed the post on how to integrate OpenFeint in 19 minutes. For the Achievements, you use the OpenFeint website to create one or more achievements to unlock (Kascade currently has 60). Originally, you had to enter your achievements in the order that you wanted them to appear, but they've pushed out an update that now allows reordering - that really helps! I used a spreadsheet to list all the names and point values for all 60 achievements so it would be easier to change and balance rather than flipping through different webpages. Then I entered them in one by one.

A few things to note:

• OpenFeint is in C++ so you have to change any files that reference it to .mm (instead of .m). To minimize this, I created an OFHandler class that made the majority of the OpenFeint API calls. My classes would then my OFHandler singleton. See the code snippet below.
• OpenFeint's SDK has all the source code, so its easier to figure out how things really work. For example, I wanted to call their [OFAchievementService unlockAchievement: <insert_value_here>] API call every time a certain number of blocks were removed. I didn't want to do a network hit every time for this, but the code showed it used a database to store the achievements that were already awarded so it wouldn't make the network call again.
• OpenFeint's Achievements do not work offline (unlike their scoreboard). Hopefully they will fix this in a new release as this would be very useful. I could write my own logic, but I'll wait and see first.
• They auto generate #defines for all your achievements so you don't have to know the numeric value. See the OFHandler.mm section below for an example of usage.

All-in-all, the OpenFeint system has been great to work with. They seem committed to adding new features and provide excellent support. If your game can take advantage of an online scoreboard/leaderboard or achievements I highly recommend it!

OFHandler.h

// your class would differ based on your achievements

@interface OFHandler : NSObject {

}

- (void) unlockAchievementForRemaining: (NSInteger) remaining colorCount: (GameMode) colorMode;

- (void) unlockAchievementForScore: (NSInteger) score;

- (void) unlockAchievementForColumns: (NSInteger) colCount totalCount: (NSInteger) total colorCount: (GameMode) colorMode;

- (void) unlockAchievementForHistory: (GameHistory*) hist;

- (void) unlockAchievementForRemovedBlocks: (NSInteger) numRemoved wildCards: (NSInteger) numWild;

+ (OFHandler*) singleton;

@end

OFHandler.mm

// A snippet of one of the calls. The #defines were auto generated by the OF site.
/**
 * This should be called upon every game over and checks the number of blocks remaining achievements.
 */
- (void) unlockAchievementForRemaining: (NSInteger) remaining colorCount: (GameMode) colorMode
{
 switch (remaining)
 {
   case 6:
     [OFAchievementService unlockAchievement:NO_BONUS_FOR_YOU_];
     break;
   case 5:
     [OFAchievementService unlockAchievement:FINALLY_A_BONUS_];
     break;
   case 4:
     [OFAchievementService unlockAchievement:OOOH_A_BIGGER_BONUS];
     break;
   ...
 }
 ...
}

Google Framework

After some further work, the above setup allows easy running of unit tests. However, debugging those Unit Tests is another story. I found another page that walks
through using the Google Toolkit for Mac to do unit testing. This allows you to run the unit tests as an executable and at least output console output (still can't seem to debug it). Note that with this framework, you need to set the active executable to your Testing executable in order to run. Any NSLog calls will be output to the console.

Unit Test Assertions

The table below is a quick reference to the different types of assertions that can be done in the UnitTest.

Table 1: Macros Available in OCUnit from Apple

+ (NSString*) getHash:(NSString *) text
{
    NSData* myData =
         [text dataUsingEncoding:NSStringEncodingConversionAllowLossy];
    CC_SHA1_CTX ctx;
    uint8_t * hashBytes = NULL;
    NSData * hash = nil;

    // Malloc a buffer to hold hash.
    hashBytes = malloc( CC_SHA1_DIGEST_LENGTH * sizeof(uint8_t) );
    memset((void *)hashBytes, 0x0, CC_SHA1_DIGEST_LENGTH);

    // Initialize the context.
    CC_SHA1_Init(&ctx);
    // Perform the hash.
    CC_SHA1_Update(&ctx, (void *)[myData bytes], [myData length]);
    // Finalize the output.
    CC_SHA1_Final(hashBytes, &ctx);

    // Build up the SHA1 data.
    hash = [NSData dataWithBytes:(const void *)hashBytes
                          length:(NSUInteger)CC_SHA1_DIGEST_LENGTH];

    // if could not create, then exit otherwise clean up
    if(hashBytes)
      free(hashBytes);
    else
      return nil;

    // now return this as an hex-encoded string
    NSMutableString *stringBuffer = [NSMutableString
                                     stringWithCapacity:([hash length] * 2)];
    const unsigned char *dataBuffer = [hash bytes];
    int i;
    for (i = 0; i < [hash length]; ++i)
    {
        [stringBuffer appendFormat:@"%02X", (unsigned long)dataBuffer[i]];
    }

    return [[stringBuffer copy] autorelease];
}

One thing to note is the you need to include the following line:

#import <CommonCrypto/CommonDigest.h>

Fortunately for me, a Lite version of Flik translates into providing just a few levels instead of the full set of levels and so I could focus on those changes.The steps below outline what was done.

Change Your Code

Where your Lite version differs from the full version at the code level, you should add #ifdef areas that are applicable to the Lite version versus the full version. While you can do an explicit #define in your code and change this before compilation, see the 'XCode Build Settings' below to see how to have XCode do this for you.

#ifdef LITE
// LITE logic goes here
#else
// FULL logic does here
#endif

To test that your targets are setup correctly, add this code somewhere:
#ifndef LITE
#error "Not Lite"
#endif // LITE

That will cause your build to FAIL on all non-Lite builds, and SUCCEED (assuming no other compile issues) on all Lite builds.   -William (from Apple Forums)

Copy Your Target

In XCode, expand the Targets item and select your application. Right click and say duplicate. At this point you probably should rename this to end in 'Lite' or 'Free'. You may want to rename the Info.plist file as well.

XCode Build Settings

For each Build Configuration that you need (e.g. Debug, Debug Device, Device Ad Hoc Distribution, Device App Store Distribution), you need to change the following settings for the Lite version. This can be found on the Build tab of the Project Settings for your Lite Target (select your target and then select the Project > Edit Active Target ... Lite).

• Info.plist File
• Product Name

You can actually specify "Configuration: All Configurations" in the top left of that screen to avoid the hassle of doing this multiple times. -William (from Apple Forums)

One other item to change on this tab is the Preprocessor Macro. This is the same as doing a #define in your code. See the section aboe on where this can be used in code.

XCode Properties Settings

If you add a space in your product name, this causes an issue in the Identifier field on the Properties tab. This normally starts out with: com.yourcompany.${PRODUCT_NAME:identifier}. If your name is 'App Lite', then this will fail during the upload process to Apple. You should explicitly set this to something unique, following Apple's recommended scheme.

While you are on this screen, you should change the Icon File to the file you will create next.

Graphics and Other Files

You should create a different icon to be displayed on the App Store. The simple way to do this is just add the word 'Lite' to it. You should make sure that this icon is added to just your Lite target and not your full target. Conversely, you should also make sure the Lite icon is not in the full target.

You should do this with all the other images or files that should be in one version and not another. You also need to prepare other images for the iTunes App Store.
That should be it. At this point you should be able to build both your full and Lite versions of your application easily. Just change the Active Target before you build.