Cocos 2D and Me

To get started writing Cocos2D code, the first thing you’ll want to do is install the Xcode templates. The templates are a great starting point for any Cocos2D project, particularly if you want to create projects using the Chipmunk or Box2d physics libraries.

First of all, make sure you have the latest release downloaded and stored somewhere suitable – I recommend in your iPhone projects folder. For reasons mentioned here, I recommend the latest unstable release (at least until v1.0 comes out).

To install the templates, you’ll want to open up the Terminal. If you’re not sure how to open up the Terminal, Spotlight is your friend. Just hit Command-Space, and type in Terminal. This is a great way to open apps or documents you don’t have quick access to, or are not sure where they are stored.

So, once the Terminal is open, navigate to where the Cocos2d project is stored. When you are inside the folder, all you need to run is

Once the script has finished executing, open up Xcode and start a new project. You should now have three new templates in there to get started with. I suggest you make a new project for each type, and run them to see what happens. It’s a good idea to have a quick look around in the code as well to see how things work.

If for some reason you want to remove the templates, or remove an older version of the templates, you can find out where they are stored by viewing the “install_template.sh” file. Open it up in TextEdit, and have a look at the first few lines of the script – most likely they will mention this directory: “/Developer/Platforms/iPhoneOS.platform/Developer/Library/Xcode/Project Templates/Application/”. Navigate to that folder from the Finder, and remove any templates you no longer want.

There are a few classes in Cocos2d that you are likely to come across over and over again. Since you’ll be seeing them so frequently, getting to know them right away seems like a good place to start.

CCDirector – The CCDirector class is in charge of running the show. If you want to pause your game for some reason (eg. a phone call comes in), it’s as simple as telling the CCDirector to pause – and another one line call will allow you to resume your game exactly where it left off.

CCScene – In a typical game, as well as the gameplay itself, there are also high scores to view, settings to change, a tutorial to read, and so on. Cocos2D handles all the movements between these different parts of your game by representing each as a CCScene. So, you might have a GameScene, a HighScoresScene, a SettingsScene, and a TutorialScene. Cocos2D then allows you to transition between these scenes at the appropriate time with ease.

CCLayer – Each scene is usually made up of one or more layers. If we are in the GameScene, then you might have a BackgroundLayer which simply displays the background, a PlayerLayer which holds your spaceship or character, and an EnemiesLayer, which holds all of the things you’re trying to kill. This allows for a good object orientated design, and allows each layer to handle input, collisions, and so on, as appropriate.

CCSprite – A CCSprite represents a graphic object. This is what you’ll use to represent your game characters, weapons, enemies, and so on. CCSprite offers a very simple means to load in graphics, move them around and do all other sorts of things to them.

CCLabel – As you might expect, this class allows you to render text on screen.

CCNode – The CCNode class is the simplest object type in the game, which everything is derived from. If it’s drawn on screen, moves around, or contains things that are drawn on screen, then it’s a type of CCNode. CCScene is a CCNode, CCLayer is a CCNode, etc. Think of CCNode as bit like the NSObject of Cocos2d.

One thing to note is that v0.9 of Cocos2d introduced the CC namespace. This means that a lot of the examples you find on the net no longer work, but it’s a fairly simple fix – just prefix any of the Cocos2d class references with “CC”. If you’re after a little bit more on the key classes, have a read of this great introduction. Just remember that the article is a bit outdated, and doesn’t include the CC namespace.

The Cocos2d for iPhone Xcode project comes with a number of demos, which are useful both for seeing visually what the engine is capable of, and for digging into the code to see how things are done.

To start, download the latest version from the official Cocos2d for iPhone website. There are a few options for which package to download, but I recommend you get the latest Unstable Version. As Cocos2d is still in pre-release the API is in somewhat of a state of flux, and it often changes some between versions. In my experience the unstable versions have actually been perfectly stable, and have the benefit of including all the latest API changes, meaning you won’t need to mess around making changes to your code later on.

If you open up the downloaded archive, you’ll see an Xcode project inside:

As you can see, I’m currently running Cocos2d v0.99.0-rc – in other words the release candidate for v1.0. Open up the Xcode project and do a Build as a sanity check to make sure everything is ok. You might get some Warnings, but these can be safely ignored.

To run the demos, you’ll probably need to make a small change to your Xcode settings. Go to the View menu, and choose Customize Toolbar. From here, you want to drag both the Active Target and the Active Executable drop downs on to your toolbar, like so:

You’ll then need to select the same thing for both the Active Target and the Active Executable, as in the image above. You might also need to change the Overview drop down so that the code runs on a version of the Simulator (or your Device, if you prefer).

At the moment there are about 40 demos you can run, so work your way through them to get a feel for the library.

Now that we’ve decided upon Cocos2D for our game engine, let’s take a look into what the engine offers. Before we get too much further in though, I’d like to recommend that if you are brand new to the iPhone platform and/or Xcode, I would highly advise that you do a little catch up reading. One of the best ways to do this is to read Beginning iPhone Development. This really is one of the best books around on how to get started developing on the iPhone, and gives a good coverage of what you can do with the platform.

Now that that’s out of the way, we can a look at what Cocos2D has to offer. If you take a look at the official Cocos2D for iPhone website, there is a quick summary in the About section of the main engine features. Let’s go over a few of them:

• Scene management – just about all games have different screens apart from the main game. These might be high scores, settings, different levels, and so on. Cocos2D lets you set these up easily, and transition between them with a number of (sometimes cheesy) effects.
• Sprites – a sprite is pretty much the technical name for a graphic or image. If your game includes any sort of graphics, generally they will be handled by the Sprite class in Cocos2D in a memory efficient manner.
• Actions – Cocos2D allows you to run all sorts of actions on your sprites, such as movement, rotation and scaling.
• Physics engine – Cocos2D integrates with two well established physics engines, Box2D and Chipmunk. Both engines allow you to easily implement complex physics interactions between objects and the game environment.
• Menus – setting up your menus and controlling the flow between the different parts of your game couldn’t be much easier.

Naturally, Cocos2D offers many other things, but the points above are probably the main features you’ll be using, at least while we get started. While you’re looking at the About page on the official site, you might as well check out the videos as well. These show off some of the different effects that the engine is capable of.

You may have heard the term “game engine” before, but never paid much attention to what it means. Game engines are generally libraries of code designed to do a lot of the hard work in creating a game. Most modern game engines are impressively comprehensive, and can include simple things like loading images and moving them around, to more complex ideas such as designing and laying out levels. There are already several game engines for the iPhone, and with all the conflicting information available online, selecting one is confusing at best. As you may have already guessed from the name/URL of this blog, I’ve already made my decision, but that doesn’t mean you’ve made yours. I also feel it’s important to know what else is out there, as a wise coder always knows what options they have, rather than how to do everything with one option.

Our Criteria

As this will be my first game, I’m going to stick with the KISS principle. Like many of you, if I make things too complicated for myself I’m going to lose heart and eventually give up. So, here’s a few points of what I’m after in a game engine, and what sort of game I want to develop:

• I’ll be making a 2D game. Adding that third dimension adds a whole new layer of complexity, and I have no idea how to deal with 3D models. Flat images I can deal with.
• I don’t want to create a puzzle game. This is simply a matter of choice, as I want to be excited by what I’m developing. Puzzle games are fun, but they don’t excite me.
• I want to understand what I’m doing. So, I’m not looking for a super high level engine which allows me to do everything quickly, but is impossibly hard to tweak once I want to do anything unusual – which is bound to happen.
• The engine I select needs a good support network. Whilst there are some really great libraries out there, without any documentation or support they’re going to have a very steep learning curve.

And that’s about it. Let’s move on at take a look at what I consider to be the main options available for an iPhone game engine.

Core Animation / Core Graphics

The Core components included in the iPhone SDK are, believe it or not, capable of powering a game. If you do enough reading on this topic, you will find many people who tell you you are wasting your time by developing a game using only the standard libraries, and to some extent this is true. As the standard Core libraries aren’t really built for developing games, they do have limitations. If your game is a simple puzzle type game where only one or two things are moving onscreen at a time, the Core libraries can be a good choice. They’re built-in, they’re free, and they’re using the language you are probably already used to, Objective-C, so there’s not much of a learning curve. There’s also going to be plenty of Apple documentation and support. The downside is that performance is going to be a problem if you start to do anything complicated. There’s a good example of developing a game using the Core libraries here.

OpenGL

OpenGL is pretty much the standard games engine for a large number of platforms, including the iPhone. It is incredibly powerful, well supported, and used in a huge number of modern games. Unfortunately, OpenGL is a pure C framework that it is not particularly intuitive, particularly for a beginner. It has been around for a very long time, and as such can feel archaic and bloated – many lines of code are required just to display a simple graphic onscreen. For those willing to invest the time and dedication, OpenGL can be a fantastic platform, but for my purposes I believe it is not a good choice. There are other libraries around which use the power of OpenGL, but provide a higher level development experience.

Torque

Torque 2D for iPhone has been developed by the well known company GarageGames. Torque has been released for many different platforms, and as such has a long solid history and is quite a popular choice. If you are planning on building a 2D game, Torque would be a good choice. It offers a visual game builder, and includes the full source with the package in case you want to make any modifications yourself. Torque also provides an easy way to port your games to other platforms, such as Xbox360 or Wii. The main reason I personally would not use Torque at this time is that I feel there’s too much of a learning curve. Torque uses it’s own scripting language, so you won’t be coding in Objective-C, and having never had any experience with game builders such as this I fear I am too far out of my depth. I don’t feel comfortable building everything with drag and drop and scripts, I want to write some actual code! Other downsides include the cost, and needing to have a “developed with Torque” splash screen displayed when launching your game (if using the indie version). However, if you think scripting and drag-and-drop appeals to you, it might be worth giving one of the demos a try, though from memory there’s no specific iPhone Torque demo available.

Unity

Unity is another drag and drop type game builder, and as such is seen as a direct competitor to Torque. Unlike Torque 2D, Unity supports both 2D and 3D games (Torque 3D for iPhone is coming though, sometime). The advantage of this is obvious, providing more flexibility in the type of games you can create. Unity also provides scripting features, but this time in C# and Javascript, so is more likely to appeal to more people. Unity reportedly also has much better documentation and support than Torque, so if I were to choose a visual game editor such as this, Unity would probably be my choice. The main reason I have not chosen Unity is that it is really a 3D game engine. Whilst 2D games certainly can be built with it, I believe this will add another layer of complexity which I just don’t need. Unity also has costs associated with it, and has the same splashscreen requirement for the cheaper version. If you do decide Unity is down your alley, there should be a demo for the iPhone available, and a great set of tutorials to get you started here.

Cocos2D

So, finally we get to Cocos2d for iPhone. Cocos2d is an open source framework built specifically for creating 2D games, which has been ported to iPhone. It has some really nice effects which you can see in the video demos, and gets some great reviews for people who are using it. All code is written in Xcode in regular Objective-C, so anyone who has done some iPhone development already should feel comfortable with the syntax at least. The catch is that documentation is sorely lacking. After a few hours of searching I only managed to come up with a small collection of articles, half of which are already out of date, so there is more of a learning curve than I was hoping for.

The Winner – Cocos2D

So, obviously I’ve chosen to go with Cocos2d, but why? Well, it fills most of my criteria. It’s specifically for 2D, so we’re keeping things simple – I don’t picture myself working on 3D games anytime soon, and I expect when I do it will be as large a jump from 2D games to 3D games, as it will be from apps to 2D games, so I don’t want to make two jumps at once. The demos are pretty convincing as to the capabilities of the engine, and writing code in Objective-C makes me feel confident enough that I will be able to understand everything that’s going on in my project. To me, Cocos2D feels like a comfortable middle ground between the low-level Core & OpenGL libraries, and the high-level Torque and Unity frameworks. Although the documentation is not as good as I would like it to be, there are active forums and Cocos2D is growing rapidly in popularity. It’s with this blog that I’m hoping to help fill the documentation hole, and provide a useful set of tutorials for people who are in the position I’m in now.

If you still haven’t made up your mind, there are some other options. Oolong, GameSalad, and Shiva are all iPhone game frameworks, but I felt they weren’t mature enough to consider seriously. Who knows though, by the time you read this entry they might be! If you’re not a big fan of Objective-C and are looking for something higher level, this thread gives some useful insights into the merits of both Unity and Torque. Finally, if you’re still feeling like you want to go with OpenGL or the Core libraries, I’d strongly recommend you keep an eye on this blog – I’m positive Cocos2D has a lot to offer you.