How to Make a Platformer Game with Cocos2D-X

Cocos2d-X Meta-Project Setup

In this chapter we'll discuss how to create your own Cocos2d-X project files from scratch for iOS, Mac, Android and Windows.


You can skip this chapter if using RapidGame. Here's how easy it is to create a new game (Node.js and Git are required) using prebuilt cocos2dx libraries so you never have to compile cocos2d-x twice:

sudo npm install rapidgame -g
rapidgame create cocos2d "Zombie Matrix" org.myorg.zombiematrix
rapidgame prebuild

From here on we'll be showing you how to create a new project with cocos2d-x with all the source files ready to be compiled.

What will you need to follow along?

First of all, you'll need to download Cocos2d-X. This tutorial is written for version 3. There's also an older version of this chapter maintained for version 2.

The iOS and Mac sections assert that you have a Mac computer and have already installed a stable release of Xcode. Xcode is a free development environment by Apple and much preferred by many a developer.

The Windows section asserts that you have a genuine copy of Windows with Visual Studio installed. You can accomplish this setup on a regular PC or use a Mac computer with Boot Camp.

The Android section asserts that you have already installed the Android SDK (which includes Eclipse) and NDK. Make sure to install the latest platform-tools, build-tools and API from the Android SDK Manager. With this setup, you can build for Android on Windows, Mac or Linux.

Keep in mind that Xcode, Visual Studio, Eclipse and even Cocos2d-X are updated often. There are new options, build settings and sometimes UI elements have been rearranged. If you run into any problems, please let us know how you solved them in the comments.

According to a recent survey we took, iOS is the most popular deployment target for Cocos2d-X developers, with Android coming in a close second. So that's where we'll start.

iOS Project From Scratch

There's now a very simple way to create a Cocos2d-X iOS project from scratch. Just open Terminal, change to your cocos2d-x directory and run the command to create a new multi-platform project:

cd Desktop/cocos2d-x-latest/
tools/cocos2d-console/bin/cocos new \
    --package com.MyCompany.AwesomeGame \
    --language cpp \
    --directory ~/Desktop \

We use the cpp language option here to create a C++ project. You can also create lua and javascript projects.

You've now got a brand-new, multi-platform game project called "MyGame" on your Desktop.

Open up ~/Desktop/MyGame/proj.ios_mac/MyGame.xcodeproj. Select "MyGame iOS" from the scheme dropdown (it might say "build-all-libs Mac" initially) and hit the Run button to check out Cocos2d-X's HelloWorld app.

Cocos2d-X's HelloWorld app

You probably noticed when you selected "MyGame iOS" from the schemes dropdown that there are many non-runnable schemes to choose from. You can hide all these non-runnable schemes. Just select "Manage Schemes..." from the scheme dropdown, uncheck the Show box next to all but "MyGame iOS" and "MyGame Mac" and click OK.

Hiding non-runnable schemes in Xcode

Alternatively, you can just remove the unwanted schemes by selecting them and clicking the "-" minus button.

Xcode Sub-Projects

Let's take a look at the project behind the scenes. It's actually quite elegant.

First of all, Cocos2d-X is included as a sub-project. It makes available many different targets that can be built and included in your game. These include the cocos2dx library for iOS & Mac, the CocosDenshion sound engine for iOS & Mac, the Box2d & Chipmunk physics engines, and many other libraries.

These libraries are included in the MyGame project as dependencies and the resulting library files are linked into the binary. View this for yourself by clicking MyGame from the project drawer and then clicking Build Phases.

Looking at the Xcode build phases

Building a project this way makes upgrading a snap. Since all the libraries are included as a single sub-project, when Cocos2d-X is upgraded the MyGame project does not have to be edited. Just copy the new Cocos2d-X into MyGame/cocos2d and that's it.

Customizing the Project

Now let's customize the project a little bit. Open Classes/HelloWorldScene.cpp and change the following line:

auto label = LabelTTF::create("Hello World", "Arial", 24);

To this:

auto label = LabelTTF::create("My Hello!", "Arial", 80);

Now Build & Run your project:

Running the MyHello iOS Xcode Cocos2dX project

The label now says "My Hello!" instead of "Hello World" and it's much bigger. You've successfully proven the project is your own.

The Mac Project

One of the best parts about creating a meta-project like this is that it re-uses the same game source code for each platform. Because we changed that one line of code to "My Hello!" it will be applied to every other platform we build for. This is where Cocos2d-X really shines.

The Mac project is already a part of the iOS project that we've been working on. Just select "MyGame Mac" from the schemes dropdown and Build & Run. After it builds all of Cocos2d-X for Mac you'll see your "My Hello!" customization.

Running the MyHello Mac Xcode Cocos2d-X project

The Android Command-line Project

Once again the meta-project comes in real handy. We already have an Android command-line project that we can customize in the folder.

You can see which Android API version it's targeted for in the file. Example:


This is the API version that will be built against (similar to the Base SDK in Xcode). Make sure you have installed this API version from the Android SDK Manager.

Your Android game can still run using earlier API versions, as specified in the AndroidManifest.xml file (similar to the Deployment Target in Xcode):

<uses-sdk android:minSdkVersion="9"/>

The folder is mostly ready to go. We just need to add a makefile for convenience. Open Terminal, switch to your MyGame/ directory, and create this makefile (or just download it):

    @if [ ! -d \${ANDROID_HOME} ]; then echo "Missing ANDROID_HOME"; exit; fi
    ant -Dsdk.dir=/Path/to/your/android/sdk debug
    adb -d uninstall com.MyCompany.AwesomeGame
    adb -d install bin/MyGame-debug.apk
    adb -d logcat | grep cocos2d
    rm -rf obj
    rm -rf bin
    rm -rf gen
    rm -rf assets
    rm -rf libs/armeabi
    rm -rf libs/armeabi-v7a
    rm -rf libs/x86
    rm -rf libs/mips

Important: make sure to change the /Path/to/your/android/sdk on line 4 to match the path where you installed your Android SDK.

Now, while still in the directory, you can just run the make command to start building your Android APK file:

Running make in the folder

When the make command is done, you'll have MyGame-debug.apk ready in the bin subfolder.

Because it's a bit tricky to get OpenGL ES 2.0 (used by Cocos2d-X) to work in the Android Emulator, I recommend attaching a real Android device via USB and running it that way.

Once you've attached your Android device via USB, just run the make run command, then tap on the MyGame app to run it. Here's a screenshot of it running on my Samsung Galaxy S:

Running MyGame on a Samsung Galaxy S Froyo Android phone

The Android Eclipse Project

Open up Eclipse and make sure you've got all the Android and C++ plugins installed. If you need some guidance getting Eclipse set up correctly, here's a great tutorial.

Follow the Eclipse instructions in MyGame/ There's a few things you'll need to setup to ensure Cocos2d-X compiles correctly. On Mac, you'll need to at least set the NDK_ROOT environment variable:

Setting up the Eclipse build environment

Now select File > New > Other... and choose "Android Project from Existing Code".

Creating a new Android project from existing code in Eclipse

Next, choose your MyGame/ folder with the Browse... button, make sure your project is selected and click Finish.

Selecting the folder and finalizing the new Eclipse project

Last, repeat the same process to add an Android project from existing code and this time choose the MyGame/cocos2d/cocos/platform/android/java folder.

Importing the Cocos2dx java project

There you go. You've got a link to MyGame and libcocos2dx in the Package Explorer. Attach your device, select the MyGame project, then click the green Play button and Run As > Android Application.

If you get errors about @Override and "The method ___ must override a superclass method" then you've got to change your Java compiler compliance level to 1.6. Open Eclipse' preferences to Java > Compiler and select 1.6. Then click "Configure Project Specific Settings..." and do the same for your project.

Wondering where Eclipse stores project file data? It doesn't. Eclipse stores only workspace data.

The Windows Project

The first step here is to get the MyGame project onto a Windows system. Once you've done that, open up Visual C++ with MyGame/proj.win32/MyGame.sln. Next, click the green Play icon to Build and Start Debugging.

Running MyHello on Win32


By now you've gone through creating a Cocos2d-X meta-project that builds and runs on iOS, Mac, Android and Windows. Congratulations.

The exciting part about it all is that the same file, HelloWorldScene.cpp, drives most of the content for this little app. Changing that one line from saying "Hello World" to "My Hello!" worked on all those platforms without any further edits.

That's all for this chapter.

Got questions? Leave a comment below. You can also subscribe to be notified when we release new chapters.

Next Chapter >

  • Jesús Bosch


    Great tutorial… but I’m frustrated with Android. The tutorial doesn’t show how to enable the debugging on Android, something that is very important. How are we supposed to develop Android games if we can’t debug them? This missing feature makes it impossible.

  • Loc Nguyen

    I create project on windows first , and then create meta-project ( copy project to new folder Desktop/MyMetaProject ) and I success with run on windows , but when I run make with terminal , I got an error

    $ make
    NDK_ROOT = E:/Download/Android/android-ndk-r8b
    COCOS2DX_ROOT = /cygdrive/c/Users/Vinh Loc/Desktop/SuperTeo meta-project/MyProject/SuperTeo/
    APP_ROOT = /cygdrive/c/Users/Vinh Loc/Desktop/SuperTeo meta-project/MyProject/SuperTeo/
    APP_ANDROID_ROOT = /cygdrive/c/Users/Vinh Loc/Desktop/SuperTeo meta-project/MyProject/SuperTeo/
    Using prebuilt externals
    Android NDK: ERROR: You NDK_MODULE_PATH variable contains spaces
    Android NDK: Please fix the error and start again.
    make[1]: Entering directory `/cygdrive/c/Users/Vinh Loc/Desktop/SuperTeo meta-project/MyProject/SuperTeo/’
    /cygdrive/e/Download/Android/android-ndk-r8b/build/core/ *** Android NDK: Aborting . Stop.
    make[1]: Leaving directory `/cygdrive/c/Users/Vinh Loc/Desktop/SuperTeo meta-project/MyProject/SuperTeo/’
    makefile:2: recipe for target `all’ failed
    make: *** [all] Error 2

    What can I do now :(

  • Loc Nguyen

    Another error here

    make[1]: Leaving directory `/cygdrive/d/SuperTeoMetaProj/MyProject/SuperTeo/’
    ant -Dsdk.dir=”C:/Program Files (x86)/Android/android-sdk” debug
    /bin/sh: ant: command not found
    makefile:2: recipe for target `all’ failed
    make: *** [all] Error 127

    I’m using cygwin terminal. So what should I do now :(

  • Painache

    A new request here. I want to create a meta-project with Box2D support and extensions(cocosbuilder reader/scroll view/edit box …etc) support.
    How can I do that?

  • Jackie

    First I want to thanks for your article . Second I want to ask can our meta-project port to BlackBerry ? And If yes, can you show me a way ? Cause I’m interested with BB and want to port my game to BB tablet os :D

  • lalan

    Excellent tutorial. We have been developing with Unity for a while and recently switched to Cocos2Dx.
    It’s nice to see how far Cocos2D community has come along in last 3 years.

  • Alan Price

    Great job. I went through several different trials on getting a multi-platform project started for cocos2d-x. This is definitely the easiest to get working and is probably the most future proof as it leverages the samples provided with Cocos.

    I will see how things go moving forward. I’m wondering as I start to add new files how many places I will need to change to keep the projects moving together in sync.

    I decided to rename projects as I went through the example. The android project was definitely the most painful. There are also a couple references to HelloCpp that will want to be changed and definitely the structure of the src directory is critical (that tripped me up as somehow I missed your comment at the end of the command line section).

  • Bagusflyer

    I got the following error:

    The import org.cocos2dx.lib.Cocos2dxActivity can not be solved.

    My Cocos2d-x version is 2.0.4 and the directory structure is exactly the same as you mentioned in the blog. Any idea? Thanks.

  • Patricio

    Hello Nat Weiss from Spain:

    First congratulations for this book. It’s too helpful and instructive.

    I have a doubt with this chapter.
    I don’t have a Mac computer and I created my meta-project starting from a PC computer with Windows XP.
    Like windows user, then I followed this tutorial from cocos2d-x web:

    I will try one’s luck with Android first. And if my game has some success, then I will try with iOS.
    Do you know if I will have problems when I want to build Mac project starting from windows user tutorial?


  • Darryl

    Just an FYI; If you’re silly like me and copy-n-paste the makefile contents, you’ll end up with an error like this:

    makefile:2: *** missing separator. Stop.

    makefile requires TABs, not spaces.

  • Jorge

    Hi Nat, I have “The import org.cocos2dx cannot be resolved” at “import org.cocos2dx.lib.Cocos2dxActivity;” line

    I have no src/org/cocos2dx/lib/ because in samples/HelloCpp didn’t exists this java. I forgot anything?

    tx in advance

  • Martin

    Excellent tutorial, I followed the ‘New iOS Project via Copying’ section however one minor issue in Xcode 4.5 was I could not rename the project without git support. This can easily be sorted with a ‘git init’ via command line in the project root folder e.g. ‘MyHello’

    In Xcode 4.5 all files are renamed correctly however you still need to update the ‘plist’ name in build settings.

  • rousing

    Great tutorial,
    As also requested by Painache. Is it possible to update it with Box2d and extensions please ?

    thank you

  • Lance Gray

    I tried several ways to make it run on Android but I can’t seem to make it work.

    I followed the “New iOS Project via Copying” part and the “The Android Command-line Project”. It compiles properly now but I can’t run “make run” and is giving me the following error: xxxxx$ make -f makefile1 run
    adb -d uninstall com.mygames.appname
    make: adb: No such file or directory
    make: *** [run] Error 1

    If I try to comment the line “adb -d uninstall com.mygames.appname”, I get the following error: xxxxx$ make -f makefile2 run
    adb -d install bin/appname-debug.apk
    make: adb: No such file or directory
    make: *** [run] Error 1

    I looked at the bin directory and the APK file is there.
    I tried using Eclipse but I am getting the “The import org.cocos2dx cannot be resolved” error in the line “import org.cocos2dx.lib.Cocos2dxActivity;” of the “src/com/mygames/appname/” file. The file “src/org/cocos2dx/lib/Cocos2dxActivity” does not exist.

    Did I just miss something? I’m using Xcode 4.5, Eclipse Indigo, and cocos2d-x-2.0.4 on a Macbook Pro ( Mav OS X 10.8 )

  • Arjun

    Something worth mentioning for Android: You need to “build” the project before importing into Eclipse. This basically involves running the script thru cygwin.

    If you are facing errors or app crash on launch in Eclipse, you probably haven’t built the code (and hence it can’t find the library).

    Also, if you see “library not found”, you probably need to import again (don’t use copy to workspace option)

  • Andy

    Anyone able to setup the ‘myhello’ android project on a windows pc – no access to a mac over xmas period.

    Problem I have, is I can’t follow the steps past installing the Android + Eclipse tools as I dont have the files,config/setup that is listed in the guide so cant create the iOS meta project etc and its not clear to me how to copy from the paralaxer code to create a new androind meta project on a windows only machine (Though I do have the paralaxer ofc, and the regular android sample apps work)

    Cheers, being thick through the post xmas fog..hehe :)


  • Mike

    I followed the tutorial up to the android segment and had success. I then renamed all my files and went a few steps further as some things still were saying HelloCpp. I honestly don’t remember the exact steps as it was somewhat trial and error. I know for a fact I did Project>Refactor>Rename, changed the ‘app_name’. Everything seemed fine and was running with the correct app labels and names inside of the IDE and on the device. Then I hopped in xCode to just do a quick change as a test and tried to re ‘make’ the build. At this point I now get the error: was modified manually! Reverting to generated version!

    01-15 15:37:26.775: E/AndroidRuntime(10606): java.lang.RuntimeException: Unable to instantiate activity ComponentInfo{}: java.lang.ClassNotFoundException: Didn’t find class “” on path: /data/app/

    Any ideas? What is the correct process for completely renaming the project from HelloCpp to whatever you want in all occurrences. Meaning so it displays correctly in Eclipse(Project Tree), all the paths like are synced and there is no more occurrence of the copied template HelloCpp. Once thats done how do you recompile updates and continue on.

  • Pedro

    Dang, i’m really confused right now!

    I’m using Windows 7 and i want to create a project that will run on both Android and iOS. How do i do that?

    You guys use a Mac to create a project to iOS, a PC with Linux to create a project do Android and a PC with Windows to create a project do Windows?!

  • Xazen

    I created a project via copying. Unforunately I get an error. “Lexical or Prepocessor Issue ‘cocos2d.h’ file not found” I tried restarting Xcode deleting derieved data.

  • Just Games


    [zipalign] Running zip align on final apk…
    [echo] Debug Package: /Users/macmac/Desktop/MyHello/projects/MyHello/
    [propertyfile] Creating new property file: /Users/macmac/Desktop/MyHello/projects/MyHello/
    [propertyfile] Updating property file: /Users/macmac/Desktop/MyHello/projects/MyHello/
    [propertyfile] Updating property file: /Users/macmac/Desktop/MyHello/projects/MyHello/
    [propertyfile] Updating property file: /Users/macmac/Desktop/MyHello/projects/MyHello/



    Total time: 9 seconds
    /Users/macmac/Desktop/MyHello/projects/MyHello/ line 5: adb: command not found
    /Users/macmac/Desktop/MyHello/projects/MyHello/ line 6: adb: command not found
    /Users/macmac/Desktop/MyHello/projects/MyHello/ line 7: adb: command not found macmac$

    im getting this error and im working on Mac OS…. Pls help me out from this problem.

  • Fernado Javier Fernandez

    Hi, great tutorial. I´m new with cocos2d-x and I´m trying to run helloworld on android using eclipse, but its really frustrating. First of all got a lot of troubles with the libraries and the configuration, when I was ready to build and launch the app, the emulator in eclipse took a lot of time getting started and it is very slow (imagine debugging your game on it), finally when it got started the application didn´t launched, I was thinking it will probably be the way I´ve had created the project but not I did it using, then I decided to run it on a virtual machine using the image of a assus tablet provided by the project android-x86 which is faster than the native emulator and again I try to deploy the app and it didn´t start in the emulator giving me an error in the console that a library could not be found. What I´m doing wrong? please help me.

  • Carlos

    This is giving me the creeps…

    I’m trying to do a cocos2d-x project in order to do the android version of my finish cocos2d ios game.

    I’ve been looking for tutorials and I can’t even have the base project…

    I have done the same as you say in the tutorial (only I added the box2d folder) but I’m stuck at this “Now, while still in the directory, you can just run the make command to start building your Android APK file:”

    Run the make command?? HOW??, If I open the terminal in the folder and just write “make” and press enter, i get an error
    make: *** No targets specified and no makefile found. Stop.

    I don’t know what to do to have a base project with cocos2d-x and box2d…. I only need the base project, and then start coding my game in eclipse…

    This is giving me the creeps, I don’t need mac, or windows or ios, I just want to have the cocos2d-x project in eclipse, and code there the game… (cause I already have finished my cocos2d ios game)

    Please help!! Thanks

  • sts2055

    For those building the project for Windows. I had to add libcocos2d as a dependency to libCocosDenshion for it to work.

  • sts2055

    First of all, thank you for this great book!
    It really helps and I even managed to run my first ever windows program, yay!
    Maybe somebody can help me with this one, though:
    I got the program working in Visual Studio, however, when I want to share it with my pal, when I click the .exe in the Debug.win32 folder, the program runs, I can see the fps indicator and all, but it doesn’t load any Sprites. How come?

  • John


    first I’d like to say thanks, I spent a few hours trying to find exactly what you have put together here, and it’s been a great help.
    though, I’m trying to get a starting windows project working and I don’t know what to do about these three errors.

    Error 4 error C1083: Cannot open include file: ‘CCStdC.h’: No such file or directory c:usersjohndesktopnew foldertrunkprojectscppcocoaplatformerproj.win32main.h 11 1 CocoaPlatformer

    Error 5 error C1083: Cannot open include file: ‘cocos2d.h’: No such file or directory c:usersjohndesktopnew foldertrunkprojectscppcocoaplatformerclasseshelloworldscene.h 4 1 CocoaPlatformer

    Error 6 error C1083: Cannot open include file: ‘cocos2d.h’: No such file or directory c:usersjohndesktopnew foldertrunkprojectscppcocoaplatformerclassesappdelegate.h 4 1 CocoaPlatformer

    if you could help asap that would be great, thanks!

  • Mazyad Alabduljaleel

    This tutorial is awesome, loved it! Kudos!

    I just really hoped that the Mac and iOS projects were fused together by cocos2d-x group in a single project, with multiple targets, cause now, each time I add a resource or source file to the iOS project, I have to do that to the Mac project as well… Kinda tedious, but not too serious.

    Android on the other hand is awesome, since it runs the script, so by modifying that script, you get an automated way to include all the new source files into the project!

    Check this out for more:

  • jimmy

    hey, I'm  really a fisher on cocos2d-x. I’ ve bought the paralaxer for development.
    As the method metioned in most cocos2dx introduce, I m succesed to runn the hellocpp on my anroid 4.0, But failed on paralaxer, with error msg ‘classnotfound with ‘. so I copy the sources into my hellocpp project classes dir, and changed the makefile.Almostly I run the game without an file woosh.wav file not found exception.
    Any recommand is prefered,thanks !

  • Nick

    I’m getting the same errors as john, but I’m not sure what you mean by “Looks like you need to setup the directories your compiler will look for header files.”

  • Adalberto

    A couple of questions:
    I’m running windows. Is there anyway to get my project to update all the different project types at once (Android, iOS, Android) when I build? I realize that once the iOS project is updated, it’ll have to be actually built on a OSX machine.

    2nd: I can get my project to build, and if I run it as a debug thing inside of Visual Studio, it’ll show up. However, the actual exe won’t open. Instead it just processes for a few seconds, then gives up.

  • NNL

    I see you have a fullscreen option on the mac, that’s great! Do you know how to implement fullscreen for win32? I’d really love to see that added. Can add so much more atmosphere to the game when it’s fullscreen.

  • Jeremy Kimayong

    Is it possible to run cocos-2dx in windows 7? Can somebody help me. :)

  • ashish

    hi i need to converteclipse project to c++ … but when writing the build command i dont know what to write in place of bash i am using cygwin and there is bash_profile… do i hav to give its path followed by bash or bash_profile

  • steve

    Firstly, thank you for such an excellent set of tutorials which has sparked my interest to get back into game coding.

    I followed happily up to running ‘’. I’ve download cocos2d-x-alpha3 but can’t find any trace of this script.

    Does anyone know if this step has changed?

  • jgg

    Hi there, Nat. I’m trying to get the apk from Windows with the makefile you provide but I’m experiencing some issues.

    First, if I execute ‘make’ in Cygwin I get

    make: execvp: ./ Permission denied
    makefile:2: recipe for target ‘all’ failed
    make: *** [all] Error 127

    It seems a Cygwin configuration error maybe?

    If I try to launch the python script from cmd (Windows command line) I get

    File “…”, line 25
    print “Can’t know cpuinfo, use default 1 cpu”
    SyntaxError: invalid syntax

    They must be silly errors. Do you know how can I solve it? Thanks in advance and sorry for now asking more ‘advanced’ questions… hahah.

  • haogle

    Description Resource Path Location Type
    *** Android NDK: Aborting . Stop. Text line 27, external location: C/C++ Problem

    i makefile it in windows eclipse.and logoff these answers
    can you tell me the right solutiom

  • Paresh Rathod

    I am surprised to see missing in download cocos2d-x-3.0rc0.
    Any solution?

  • Kaylee

    Appreciation to my father who told me regarding this webpage, this website is genuinely awesome.

  • -->