Read more about this book

(For more resources on this subject, see here.)

Downloading Cocos2d for iPhone

Visit http://www.cocos2d-iphone.org for downloading the latest files. Search the downloads page, and there you will find the different versions available. As of this writing, Version 0.99.5 is the latest stable version.

Once you have downloaded the file to your computer, uncompress the folder to your desktop, and rename it to Cocos2d. Open the uncompressed folder and take a look at its contents. Inside that folder, you will find everything you will need to make a game with Cocos2d. The following is a list of the important folders and files:

• Cocos2d: The bread and butter of Cocos2d.
• CocosDenshion: The sound engine that comes along.
• Cocoslive: Cocos2d comes packed with its own highscore server. You can easily set it up to create a scoreboard and ranking for your game.
• External: Here are the sources for Box2d and Chipmunk physics engines among other things.
• Extras: Useful classes created by the community.
• Resources: Images, sounds, tilemaps, and so on, used in the tests.
• Templates: The contents of the templates we’ll soon install.
• Test: The samples used to demonstrate all the things Cocos2d can do.
• Tools: Some tools you may find useful, such as a ParticleView project that lets you preview how particles will look.
• License files: They are here in case you need to look at them.

We’ll start by taking a look at the samples.

Time for action – opening the samples project

Inside the cocos2d-iphone folder, you will find a file named cocos2d-iphone. xcodeproj. This project contains all the samples and named tests that come with the source code. Let’s run one of them.

1. Open the .xcodeproj file: In the groups and files panel you will find the source code of all the samples. There are more than 35 samples that cover all of the capabilities of Cocos2d, as shown in the following screenshot:

   

2. Compile and run the SpriteTest: This project comes with a target for each of the available tests, so in order to try any of them you have to select them from the overview dropdown.
   Go ahead and select the SpriteTest target and click on Build and Run. If everything goes well the test should start running. Play a little with it, feel how it behaves, and be amazed by the endless possibilities.

   

 

What just happened?

 

You have just run your first Cocos2d application. If you want to run another sample, just select it by changing the “Active target”. When you do so, the “active executable” should match to the same; if it doesn’t select it manually by selecting it from the overview dropdown box. You can see which “active target” and “active executable” is selected from that overview dropdown box, they should be selected.

Installing the templates

Cocos2d comes with three templates. These templates are the starting point for any Cocos2d game. They let you:

• Create a simple Cocos2d project
• Create a Cocos2d project with Chipmunk as physics engine
• Create a Cocos2d project with Box2d as physics engine

Which one you decide to use for your project depends on your needs. Right now we’ll create a simple project from the first template.

Time for action – installing the templates

Carry out the following steps for installing the templates:

1. Open the terminal. It is located in Applications Utilities | Terminal|.
2. Assuming that you have uncompressed the folder on your desktop and renamed it as Cocos2d, type the following:

   cd desktop/Cocos2d
   ./install_template.sh

   You will see a lot of output in the terminal (as shown in the following screenshot); read it to check if the templates were installed successfully.

   

   If you are getting errors, check if you have downloaded the files correctly and uncompressed them into the desktop. If it is in another place you may get errors.

We just installed the Xcode templates for Cocos2d. Now, each time you create a new project in Xcode, you will be given the choice of doing it by using a Cocos2d application. We’ll see how to do that in a moment.

Each time a new version of Cocos2d is released, there is a template file for that version. So, you should remember to install them each time. If you have a lot of older templates and you want to remove them, you can do so by going to Developer/Platforms/iPhoneOS. platform/Developer/Library/Xcode/Project Templates/Application and deleting the respective folder.

 

What just happened?

 

Templates are very useful and they are a great starting point for any new project. Having these templates available makes starting a new project an easy task. You will have all the Cocos2d sources arranged in groups, your AppDelegate already configured to make use of the framework and even a simple starting Layer.

Creating a new project from the templates

Now that you have the templates ready to use, it is time to make your first project.

Time for action – creating a HelloCocos2d project

We are going to create a new project named HelloCocos2d from the templates you have just installed. This won’t be anything like a game, but just an introduction on how to get started. The steps are as follows:

1. 1. Open Xcode and select File New project| (Shift + cmd + N).

2. Cocos2d templates will appear right there along with the other Xcode project templates, as shown in the following screenshot:

1. Select Cocos2d-0.99.1 Application.
2. Name the project HelloCocos2d and save it to your Documents folder.

Once you perform the preceding steps, the project you just created should open up. Let’s take a look at the important folders that were generated:

• Cocos2d Sources: This is where the Cocos2d source code resides. Generally, you won’t touch anything from here unless you want to make modifications to the framework or want to know how it works.
• Classes: This is where the classes you create will reside. As you may see, two classes were automatically created, thanks to the template. We’ll explore them in a moment.
• Resources: This is where you will include all the assets needed for your game.

Go ahead and run the application. Click on Build and go and congratulate yourself, as you have created your first Cocos2d project.

Let’s stop for a moment and take a look at what was created here.

When you run the application you’ll notice a couple of things, as follows:

• The Cocos2d for iPhone logo shows up as soon as the application starts.
• Then a CCLabel is created with the text Hello World.
• You can see some numbers in the lower-left corner of the screen. That is the current FPS the game is running at.

In a moment, we’ll see how this is achieved by taking a look at the generated classes.

 

What just happened?

 

We have just created our first project from one of the templates that we installed before. As you can see, using those templates makes starting a Cocos2d project quite easy and lets you get your hands on the actual game’s code sooner.

Managing the game with the CCDirector

The CCDirector is the class whose main purpose is scene management. It is responsible for switching scenes, setting the desired FPS, the device orientation, and a lot of other things.

The CCDirector is the class responsible for initializing OpenGL ES.

If you grab an older Cocos2d project you might notice that all Cocos2d classes have the “CC” prefix missing. Those were added recently to avoid naming problems. Objective-c doesn’t have the concept of namespaces, so if Apple at some point decided to create a Director class, those would collide.

Types of CCDirectors

There are currently four types of directors; for most applications, you will want to use the default one:

• NSTimer Director: It triggers the main loop from an NSTimer object. It is the slowest of the Directors, but it integrates well with UIKit objects. You can also customize the update interval from 1 to 60.
• Mainloop Director: It triggers the main loop from a custom main loop. It is faster than the NSTimer Director, but it does not integrate well with UIKit objects, and its interval update can’t be customized.
• ThreadMainLoop Director: It has the same advantages and limitations as the Mainloop Director. When using this type of Director, the main loop is triggered from a thread, but it will be executed on the main thread.
• DisplayLink Director: This type of Director is only available in OS 3.1+. This is the one used by default. It is faster than the NSTimer Director and integrates well with UIKit objects. The interval update can be set to 1/60, 1/30, or 1/15.

Those are the available Directors, most of the times you will not need to make any changes here.