Cocos2D-iPhone and project setup

I’ve been building iPhone applications for a while now and some very simple games using UIKit but unfortunately UIKIT as it stands is just not cut out for games. So I’ve been looking at different frameworks that I could use, and after trying a few I stumbled across the fantastic Cocos2D framework.

I’m always a bit cautious when it comes to learning frameworks, preferring to read the docs, see examples and perform some small test apps before really committing to learning how to develop using it. After doing just that I took the plunge and began developing using it and found that it’s a great framework to have under your belt for iPhone games.

So for the last month I’ve been hammering away at creating a small iPhone game using the fantastic Cocos2D-iPhone framework. The game is really just a test bed to get to grips with everything in Cocos2D land, and there’s a lot!

My main gripe with Cocos2D is the documentation of the project. It’s just not that detailed but it’s definitely improving. What the Cocos2D team (riq?) have provided us with are an excellent set of test apps that come bundled with the source. These tests show lots of the functionalities of the framework in use and are excellent resource to use when it comes to learning Cocos2D.  If you ever need to see how implement AtlasSprites for example, open the AtlasSprite test and you will have a wealth of source to read, learn and use.

I’m hoping to put together a few tutorials together on my travels down the Cocos2D path, hopefully they might be helpful to some of you out there or even if your just curious about the framework. Give it a whirl!

Some initial links for you:

Project Home and list of features (note: OpenGL support, this framework is fast!):
http://code.google.com/p/cocos2d-iphone/

Project Blog

http://www.cocos2d-iphone.org/

Keith Peters (note: he has some great Objective-C and Cocos2D tutorials):

http://www.bit-101.com/blog/?p=2115

Videos (note: these are a great taster for what is capable in Cocos2D):
http://www.youtube.com/watch?v=GNYbYcIqlxM&feature=player_embedded
http://www.youtube.com/watch?v=JjDTpWFl2kA&feature=player_embedded
http://www.youtube.com/watch?v=UNHIy4aROp8&feature=player_embedded

Getting Started

The first thing you will need is to download the framework from: http://cocos2d-iphone.googlecode.com/files/cocos2d-iphone-0.8.1.tar.gz

Once you’ve got this, unzip and keep it somewhere… it’s invaluable for learning! Setting up a project to use Cocos2D can be pretty time consuming so we can install ourselves a handy template to save some time each time we create a new project. Open yourself a new terminal window, cd to the newly unzipped folder containing the Cocos2D source and run the installation script by typing:

1

./install_template.sh

The script should run and you will see the following text:

cocos2d-iphone template installer
…creating destination directory: /Developer/Platforms/iPhoneOS.platform/Developer/Library/Xcode/Project Templates/Application/cocos2d-0.8.1 Application/
…copying template files
…copying cocos2d files
…copying CocosDenshion files
…copying cocoslive files
…copying cocoslive dependency files
done!

As long as you see this text your Xcode template has been installed and your ready to go, easy huh? We’re going to quickly setup the obligatory ‘Hello World’ project (it’d be rude not to I think!) so boot up Xcode and in the templates you should have a shiny new Cocos2D project icon there, select this and create your project (note: I named mine HelloWorld so it may be a good idea to keep the project name the same to make it a little easier to follow).

Once Xcode has finished creating the project, open the Classes group and you will find your appDelegate.m file, it’s probably a good idea to start with this file as there are some differences to the standard appDelegate that your probably used to with UIKit development. The first difference you will notice is the setup of the Director in lines 31-33.

The Director is a Singleton Scene manager, so it’s not instantiated as such but it’s setup in the appDelegate. The views that you use in Cocos2D are called Scenes and in the Scene you have Layers to better organise the content. The Directors role is to manage all of these, displaying Scenes and Layers, setting orientation and other related properties. As you can see in these lines the Director properties used set the orientation to horizontal, the animationInterval (think fps) to 1.0/60 (60fps) and finally shows us a FPS counter, which is pretty handy to have when developing due to the iPhone’s limited resources, it’s very easy to make the fps take a nose dive! You can see a little below that the Director is attached in a window, with regular iPhone development you should be used to using Windows and attaching Views to the Window, its essentially the same principal just with one more step, it now goes Window, Director as Child and Scene and Layer controlled by that as you can see with the final line where the Director is instructed to run the HelloWorld Scene.

If we take a look at the HelloWorldScene.h header file next we can see the template has already created a HelloWorld Layer in the Scene ready for us. Switching over to the HelloWorldScene.m implementation file we can the Scene object created and inside it instantiates the Layer node in the HelloWorldScene and adds it to the display list.

Stepping a bit deeper in to the HelloWorldScene.m file we need to change the contents of the HelloWorld Layer, as standard the Xcode template adds it’s own minimal Hello World example as an example entry point to the application. We’re going to upgrade this by adding some sprites and a small animation loop.

Save the following two images…

and drag and drop them in to your Resources group in Xcode. You will have a window appear, before you press the Add button make sure you select the ‘Copy items’ tick box so Xcode copies the images to the correct place in the projects directory structure rather than just referencing the ones you dragged in.

Remove the following lines from the Layer init method in HelloWorldScene.m:

1
2
3
4
5
6
7
8
9
10
11

// create and initialize a Label
Label* label = [Label labelWithString:@"Hello World" fontName:@"Marker Felt" fontSize:64];
 
// ask director the the window size
CGSize size = [[Director sharedDirector] winSize];
 
// position the label on the center of the screen
label.position =  ccp( size.width /2 , size.height/2 );
 
// add the label as a child to this Layer
[self addChild: label];

And replace them with the following lines:

1
2
3
4

// add the background image
Sprite *backdrop = [Sprite spriteWithFile: @"backdrop.jpg"];
[backdrop setPosition:ccp(240,160)];
[self addChild:backdrop];

The first line creates a Sprite object from the image file in the Resources directory. We then set the position of the image to centre of the screen, landscape mode is 480 pixels wide by 320 pixels high, so we set the position to 240×160.

We’ll cover this in the next tutorial but for now it’s just handy to remember that the iPhone coordinate space’s 0 point is bottom left of the screen, opposed to top left like Flash. Objects such as Sprites have their registration point in the centre of the object, so for a 64×64 pixel Sprite, the registration point will be 32×32.

Lastly the code adds the Sprite to the display list. Lets do this again and add another image, just below the previous code add the following code:

1
2
3
4

// add the hello image
Sprite *hello = [Sprite spriteWithFile: @"hello.png"];
[hello setPosition:ccp(240,160)];
[self addChild:hello];

So we should now have two images Lastly, and I’ll skip over this without explaining too much as the animation functionality in Cocos2D requires it’s own tutorial. Essentially, this code makes the logo grow and shrink back down to size.

1
2
3
4

// add some animation
id scaleAnim = [ScaleBy actionWithDuration:1.0 scale:1.1];
[hello runAction: [RepeatForever actionWithAction:
[Sequence actions: scaleAnim, [scaleAnim reverse], nil]]];

Once you’ve completed all of this, press that ‘Build and Go’ button on your Xcode toolbar and you’re done! Your Hello World Cocos2D-iPhone app should be up, running and looking like the following screenie. Great stuff.

I’ve attached the xCode project as a zip file if you need it, you can download it from HERE.

Quick Update: Had an email asking about the new Splash Screen in 0.8.1. If you don’t like the Cocos2D Splash Screen that appears when booting the application, you can remove it by simply deleting the Default.png file from your Resource Group in Xcode.

Hope you enjoyed the tutorial, I have some ideas on where to go with the next few tutorials but if there are any specific topics you’d like let me know! Also any comments, sugestions for improvement always welcome too!

anton.