Cocos2d for iPhone 0.99 Beginner's Guide

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.

Try taking a look at all of the samples included with Cocos2d; some are just performance tests, but they are still useful for knowing what to expect from the framework and what it can do.

Although these tests don't make anything that looks like a game, they are useful for learning the basics, and they are very good consulting material. So, when you are in doubt and reading the source code does not help, check these examples, and you will surely find your answer.

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.

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.

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

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

A lot is happening in here. Don't worry if you don't understand it yet, as you won't have to deal with most of this stuff until you have advanced more into your game.

Let's analyze each line in here, as follows:

// Try to use CADisplayLink director
	// if it fails (SDK < 3.1) use the default director
	if( ! [CCDirector setDirectorType:CCDirectorTypeDisplayLink] )
		[CCDirector setDirectorType:CCDirectorTypeDefault];

These lines of code set the type of director that will be used. If you are targeting your game for OS 3.1 + it will use the DisplayLink Director. Let's take a look at each of them.

Let's continue looking at the code generated in the AppDelegate.

// Use RGBA_8888 buffers
	// Default is: RGB_565 buffers
	[[CCDirector sharedDirector] setPixelFormat:kPixelFormatRGBA8888];
	
	// Create a depth buffer of 16 bits
	// Enable it if you are going to use 3D transitions or 3d objects
//	[[CCDirector sharedDirector] setDepthBufferFormat:kDepthBuffer16];
	
	// Default texture format for PNG/BMP/TIFF/JPEG/GIF images
	// It can be RGBA8888, RGBA4444, RGB5_A1, RGB565
	// You can change anytime.
	[CCTexture2D setDefaultAlphaPixelFormat:kTexture2DPixelFormat_RGBA8888];

The preceding lines set the Texture's format and definition. We'll talk about this in the next chapter.

[[CCDirector sharedDirector] setDeviceOrientation:CCDeviceOrientationLandscapeLeft];

The preceding line of code sets the orientation of the device. You can choose from any four types of orientations.

[[CCDirector sharedDirector] setAnimationInterval:1.0/60];

This sets the frames per second that the application will run at. By default, it runs at 60 fps but sometimes you may need to set it at 30 fps for performance reasons. 60 fps is also the highest framerate that the iOS devices can support.

[[CCDirector sharedDirector] setDisplayFPS:YES];

Remember the numbers that appear at the lower-left corner? They show the current FPS. These can be removed by commenting this line or setting it to NO.

Finally:

 [[CCDirector sharedDirector] runWithScene: [HelloWorld scene]];

This runWithScene method tells Cocos2d to start running with a given CCScene. In this case, we are starting it with the scene created by HelloWorld.

The CCDirector handles the scene management. It can tell the game which scene to run, suspend scenes, and push them into a stack. In Chapter 5, you'll learn how to do this, for now should know that in the AppDelegate you need to tell the Director which is the scene you wish run when starting the application.

Take a look at the following method that is implemented. Those are methods found in any iPhone application, but the template has done the work of adding some useful and necessary calls.

- (void)applicationWillResignActive:(UIApplication *)application {
	[[CCDirector sharedDirector] pause];
}

When your game is about to stop being active (for example, when you lock the screen), the applicationWillResignActive: method is called. The template added the pause method from the CCDirector class. This method will pause all the timers and set the FPS to a low value, so the application does not consume much CPU.

- (void)applicationDidBecomeActive:(UIApplication *)application {
	[[CCDirector sharedDirector] resume];
}

On the other side, when the application becomes active again (for example, you unlocked the screen) applicationDidBecomeActive: method will be called. The template will add the resume method from the CCDirector class. This method resumes the timers.

In the following chapters, you'll learn how to display a UIAlert, so that the action does not resume instantly. Later on, you'll learn how to do a nice pause screen with options to resume and quit the game.

- (void)applicationWillTerminate:(UIApplication *)application {
	[[CCDirector sharedDirector] end];
}

When you quit your game (be it by pressing the home button or answering a call) the applicationWillTerminate: method will be called. This is a good time to save your game's state, if you need to.

We took a look at the code generated by the template. This particular template just creates a scene, which contains a layer that displays some text. Texts are displayed using one of the three different types of labels which are subclasses of CCNode.

Everything that is a subclass of CCNode has the following features:

In the preceding example we changed one of the label's properties.

label.position =  ccp( size.width /2 , size.height/2 );

This is only one of the several properties CCNodes have that can be modified to suit your needs.

Let's have a quick look at some of them:

As you learned before, nodes can contain other nodes. Cocos2d provides several methods for adding nodes inside other nodes, retrieving them, and even removing them. These are as follows:

When a CCNode is added to or removed from the stage, a couple of useful callback methods that are called, which are as follows:

You have just learned how to include simple text into your layer, why don't you try the following?

You may notice that moving the label that is the parent of the other one causes both of them to move. This is because of the parent-children relationship between them. This is very useful in most cases.

CCNodes can schedule selectors to run at an interval of seconds. This gives them a lot of versatility. You can use timers in the following two ways:

In the previous example, we used timers to have a Unit object fire a bullet each second after its creation.

You can use timers to just call a method once, but instead of at that precise moment you could have it scheduled and called some seconds after that.

For starters, we have made the worst units of any game. These units will fire a bullet and then start destroying themselves. After a couple of seconds of explosions (don't you see them?), they will be gone. So, let's go through the new code step by step, as follows:

[self fireAndDestroy];

As soon as the object is initialized, the fireAndDestroy method is called.

-(void)fireAndDestroy
{
	NSLog(@"FIRED!!!");
	NSLog(@"Destroying...");
	[self schedule:@selector(destroy) interval:3];
}

This method just prints some text to the Console and then schedules the destroy method to run every three seconds.

-(void)destroy
{
	[self unschedule:@selector(destroy)];
	NSLog(@"Unit Destroyed.");
	[self release];
}

We just want this method to be called once. So, we use the unschedule CCNode method to stop the selector that is passed from being called over and over. Then it prints a message and we release the object.

So, what we are doing here is having a method run after three seconds and then stopping it, thus calling it just once.

That is all there is for CCNodes right now. Remember that you will use them a lot when making your games, as they are the base class for almost everything that you wish to show onscreen. In the next chapter, you will learn how to use CCSprites, another subclass of CCNode.

We have just seen how to open the Xcode's Console. Now, you can get a lot more information from Cocos2d debug messages, such as when a particular object is dealloced.

The preceding messages are the types of messages you can get from the framework. These ones in particular are deallocing messages that allow us to know when Cocos2d has, for example, released memory for a given texture which it is not using anymore.

Cocos2d debug messages can really help you save time when searching for these kinds of bugs. Thanks to the built-in debug messages, you can get an idea of what is happening while the application is running.

As debug messages are written to the console, many times when you have a lot of things going around in your game it will start running slowly. In such cases, you may want to prevent Cocos2d from logging all that useful data. If you follow the preceding steps you will be able to switch the debug logging on and off at will.