How To Make A Simple iPhone Game with Cocos2D 2.X Tutorial

Ninjas Going Pew-Pew!

Ninjas Going Pew-Pew!

Note from Ray: You guys voted for me to update this classic beginning Cocos2D tutorial series from Cocos2D 1.X to Cocos2D 2.X in the weekly tutorial vote, so your wish is my command! :]

This tutorial series is now fully up-to-date for Cocos2D 2.X, Xcode 4.5, and has a ton of improvements such as Retina display and iPhone 4″ screen support. Here’s the pre Cocos2D 1.X version if you need it!

Cocos2D is a powerful library for the iPhone that can save you a lot of time while building your iPhone game. It has sprite support, cool graphical effects, animations, physics libraries, sound engines, and a lot more.

Back when I first started learning Cocos2D, there were several useful tutorials on getting started with Cocos2D out there, but I couldn’t find anything quite like what I was looking for – making a very simple but functional game with animation, collisions, and audio without using too many advanced features.

I ended up making a simple game of my own, and thought I’d write a tutorial series based on my experience in case it might be useful to other newcomers.

This tutorial series will walk you through the process of creating a simple game for your iPhone with Cocos2D, from start to finish. You can follow along with the series, or just jump straight to the sample project at the end of the article. And yes. There will be ninjas.

(Jump to Part 2 or Part 3 of the series.)

Downloading and Installing Cocos2D

You can download Cocos2D from the official Cocos2D-iPhone home page.

You’ll notice there are several different choices you have about which version to download: Cocos2D 1.X vs Cocos2D 2.x, and stable vs stable choices. Let’s go over them.

Cocos2D 1.X vs Cocos2D 2.X

The main difference between these two versions is that under the hood, Cocos2D 1.X is made with OpenGL ES 1.X, and Cocos2D 2.X is made with OpenGL ES 2.X. Unless you have prior experience with OpenGL, this probably doesn’t mean much to you :]

All you need to know for now is the following:

• Cocos2D 1.X has been around longer. So there’s a lot of code out there that only works with Cocos2D 1.X. This is changing though, as more and more people move to Cocos2D 2.X!
• Cocos2D 2.X can use shaders. Shaders are a fancy thing in OpenGL ES 2.X that allows you to create some cool effects that you just can’t do with OpenGL ES 1.X.

Although both versions of Cocos2D work fine and there are tons of great games made with both versions, in this tutorial you’ll use the latest and greatest, Cocos2D 2.X. :]

Cocos2D Stable vs Unstable

You’ll also notice there’s “stable” and “unstable” versions.

I’ve noticed that generally it takes a long time for useful new features to move from “unstable” to “stable.” So I tend to go for the “unstable” versions so I have all the good new stuff. Don’t worry, even though it’s called “unstable” it’s actually pretty good usually :]

So in this tutorial, you will use the “unstable” version.

Conclusion

For this tutorial, download the latest unstable version of Cocos2D 2.X.

After you pull down the code, you’ll want to install the useful project templates. Open up a Terminal window to the directory you downloaded Cocos2D to, and enter the following command:

./install-templates.sh -f -u

You should see “Installing cocos2d templates” and a bunch of messages. Congrats – you’re now ready to work with Cocos2D!

Note: If you already have Cocos2D 1.X installed and are worried about installing Cocos2D 2.X because it might override your current Cocos2D 1.X templates, don’t panic! :] Cocos2D 2.X installs its templates in a separate folder, so you can have the templates for both versions of Cocos2D installed side by side.

Hello, Cocos2D!

Let’s start by getting a simple Hello World project up and running by using the Cocos2D template you just installed. Start up XCode and create a new Cocos2D project by selecting the iOS\cocos2d v2.X\cocos2d iOS template, and name the project Cocos2DSimpleGame.

Go ahead and build and run the template as-is. If all works OK, you should see the following:

Cocos2D is organized into the concept of scenes, which are kind of like “levels” or “screens” for a game. For example you might have a scene for the initial menu for the game, another for the main action of the game, and a game over scene to end.

Inside scenes, you can have a number of layers (kind of like in Photoshop), and layers can contain nodes such as sprites, labels, menus, or more. And nodes can contain other nodes as well (i.e. a sprite could have a child sprite inside it).

If you take a look at the sample project, you’ll see there are two layers – an IntroLayer and a HelloWorldLayer, each of which has a scene that contains it.

In this tutorial, you will be working with the HelloWorldLayer. Open up HelloWorldLayer.m and look at the init method. You’ll see it’s adding a “Hello World” label and a menu right now. Next you’ll take that out, and put a sprite in instead.

Adding A Sprite

Before you can add a sprite, you’ll need some images to work with. You can use the ones my lovely wife has created for the project by downloading the resources for this tutorial.

Once you’ve downloaded the resources, unzip the file, drag everything over to the Resources folder in XCode, and make sure “Copy items into destination group’s folder (if needed)” is checked.

Now that you have your images, you have to figure out where you want to place the player. Note that in Cocos2D the bottom left corner of the screen has coordinates of (0,0) and the x and y values increase as you move to the upper right. Since this project is in landscape mode, this means that the upper right corner is (480, 320) if you’re running on a 3.5″ screen, or (568, 320) if you’re running on a 4″ screen.

Note: Those of you who have been programming on an iOS for a while might think to yourself, “Wait a minute – I thought the 4″ screen was 1136×640 pixels, not 568×320 pixels!”

You are right about that, but Cocos2D works with points, not pixels. On Retina display devices, 1 point = 2 pixels, so 1136×640 pixels = 568×320 points. This is quite handy, because if you use points in your game, your coordinates can be the same for both retina and non-retina displays!

Also note that by default when you set the position of an object, the position is relative to the center of the sprite you are adding. So if you wanted your player sprite to be aligned with the left edge of the screen horizontally, and vertically centered:

• For the x coordinate of the position, you’d set it to [player sprite’s width]/2.
• For the y coordinate of the position, you’d set it to [window height]/2.

Here’s a picture that helps illustrate this a bit better:

So let’s give it a shot! Open HelloWorldLayer.m, and replace the init method with the following:

- (id) init
{
    if ((self = [super init])) {
        CGSize winSize = [CCDirector sharedDirector].winSize;
        CCSprite *player = [CCSprite spriteWithFile:@"player.png"];
        player.position = ccp(player.contentSize.width/2, winSize.height/2);
        [self addChild:player];
    }
    return self;
}

You can build and run it, and your sprite should appear just fine, but note that the background defaults to black. For this artwork, white would look a lot better.

One easy way to set the background of a layer in Cocos2D to a custom color is to use the CCLayerColor class. So let’s give this a shot. Open HelloWorldLayer.h and change the HelloWorld interface declaration to read as follows:

@interface HelloWorldLayer : CCLayerColor

Then click on HelloWorldLayer.m and make a slight modification to the init method so you can set the background color to white:

if ((self = [super initWithColor:ccc4(255,255,255,255)])) {

Go ahead and compile and run, and you should see your sprite on top of a white background. w00t your ninja looks ready for action!

Note: You may have noticed that there are actually two versions of the player image included in the resource pack: player.png (27×40 pixels), and player-hd.png (double the size – 54×80 pixels).

This shows a really cool feature of Cocos2D – it’s smart enough to substitute the high resolution graphics when you’re running on a Retina display! Just put in some artwork that is double the size and add an -hd extension. This is similar to the @2x behavior that UIKit supports.