Cocos2d for iPhone is an OpenGL ES based library for creating games on the iPhone, iPod touch, and iPad. This document assumes as little previous knowledge as possible, and guides you through setting up and getting started with Cocos2d.
If you don't already have the iOS Software Development Kit (SDK) from Apple, you'll first need to get that from the iOS Development Center. The SDK includes Xcode, which is Apple's Integrated Development Environment (IDE), which you use to edit and compile your programs. It includes the code libraries, documentation, and so on needed for general iOS development.
You may need to sign up for the Apple Developer Program in order to download the SDK. Signing up is free (though you'll later need to upgrade to a $99 membership if you want to submit your app to the App Store).
(Note that it's common to use the term “iPhone development” even when you are really thinking of the iPod touch or the iPad – all three of these use the iOS, and are very similar from the point of view of the software developer.)
The iOS SDK is a big download, and a fairly lengthy installation too, so start this step as soon as possible, and find something else to do while you're waiting for it to complete.
Grab the “Stable Version” tarball from the download page. Double-click it in the Finder to unpack it. The result should be a set of files like this:
What is all that stuff, you ask? Most of those are actually plain text files, though Finder doesn't realize this because they don't use standard extensions. No matter: any of the capitalized files, like AUTHORS, CHANGELOG, LICENSE.box2d, etc., can be dragged right onto your favorite text editor (TextWrangler is a good free one, but there are plenty others to choose from).
You should in particular read the README file, which further defines what's in the various files, and contains a few tips on getting started (though not in as much detail as this lesson).
Perhaps the most important file not mentioned by the README is the Xcode project, cocos2d-ios.xcodeproj. Open this in Xcode.
This giant project contains all the source code for cocos2d, along with a large number of simple test/demo sub-projects. Running these is a great way to explore cocos2d's capabilities, and reading their source is a great way to learn how things are done by the cocos2d gurus.
To select a test to run, you need to set both the “Active Target” and the “Active Executable”. There are two ways to do this. The first method is to use the “Set Active Target” and “Set Active Executable” submenus under the Project menu. The second method is to put these options into the main toolbar; under the View menu, choose “Customize Toolbar…” and then drag the “Active Target” and “Active Executable” items into the toolbar at the top of the window. Then you can choose your target and executable there.
With either method, start by choosing the Active Target that you want to run – for example, “SpriteTest” or “ParticleTest”. You should find that the Active Executable automatically changes to match, but if for some reason it fails to do so, manually pick the corresponding Active Executable.
Previous two paragraphs are valid for Xcode 3. If you are using Xcode 4 you have to select a scheme, which specifies which targets to build, what build configuration to use, which debugger to use, and which executable to launch. Just Option + Click to Run button and select your scheme from the drop down list – for example, “SpriteTest” or “ParticleTest”.
Then just click the “Build and Run” (or “Build and Debug”) button. The project will be compiled, and the iPhone/iPad simulator will launch and run the demo. In case you get errors, go to Projects→ Edit Project Settings → Build and make sure C/C+ Compiler Version is “GCC 4.2” and not LLVM GCC 4.2 or some other.
Explore a few of the test/demo targets, and then you should start poking around in their source code. You'll find all the test code – that is, code similar to what you'd write for your own apps – inside the “tests” folder in the “Groups & Files” pane on the left side of the window. File names generally match the target name; for example, the source code for ParticleTest is in ParticleTest.h (the header file) and ParticleTest.m (the source file, where most of the important stuff is found).
Finally, you will want at some point to learn some Xcode debugging techniques, so you know how to pause the program at certain points in your code, examine variables, have the computer log values (or even speak them out loud!) as the code executes, and so on. If all this is new to you, don't worry about it too much now, but just remember that those things are possible, and visit that link when you're ready.
There is actually nothing you must install to use Cocos2d. It's a source library, and if you include the appropriate sources into an appropriately-configured project, it will work.
But to make this setup easier, cocos2d comes with many Xcode project templates. These let you easily create projects set up for cocos2d, with some optional components:
To install the templates, you should launch the Terminal application, and enter something like:
cd cocos2d-iphone ./install-templates.sh -u
(But replace “cocos2d-iphone” on that first line with the path to wherever your cocos2d-iphone folder actually lives – an easy way to get that is to type “cd ” and then simply drag the folder from the Finder into your terminal window.)
If the destination directories for the templates already exist, the install script will skip copying. You can force the install with:
./install-templates.sh -f -u
Once you have installed the templates, you can start a new project from Xcode:
You can (and should!) run the project at this point, and see a simple “Hello World” appear in the iPhone simulator. From there, it's just a matter of adding the “real” resources and code for your own particular game or demo.
You're on your way! Take a moment to appreciate what you've accomplished already:
That's a lot of progress! Now you're ready to start learning more about how cocos2d works, and what you need to do to make a real demo or game.
Start by carefully reading the basic concepts page, which gives you the “big picture” of how the cocos2d API works and what the most important terms mean. Then proceed to Lesson 2. Your First Game for a step-by-step tutorial.