Posted by & filed under Cocos2d, iOS.

How to start a Cocos2d-X project designed for both iPhone/iPad and Android

The Cocos2d-x project is always updating, so the latest tutorials on setting up a hybrid work environment aren’t completely accurate.

Versions for this tutorial:

Cocos2d-x: cocos2d-2.0-x-2.0.2 @ Aug 30 2012
XCode: v4.5
Android NDK: Android NDK, Revision 8b (July 2012)

Here’s the basic outline:

  1. Install Cocos2d-x
  2. Install the XCode templates
  3. Create an iPhone project
  4. Create an Android project
  5. Move the necessary Android files
  6. Change the Android files to fit the new location

Install Cocos2d-x

Download cocos2d-2.0-x-2.0.2 @ Aug 30 2012 and unzip it somewhere, such as your home directory.

Install the XCode templates

In the Terminal, go to the Cocos2d-x directory, then type:


This will give you a few options in the XCode New Project window.

Create an iPhone project

In XCode, click File->New->Project, create a new cocos2dx_box2d project, and name it anything (for example, ‘testgame’).

This will create a test game using Cocos2d-x and Box2D. Test it to make sure it runs on your system.

Create an Android project

First you need to set some environment variables. In, edit the following lines near the top:

# set environment paramters

Point them to your own NDK and Android SDK paths.
If you want to keep an NDK_ROOT environment variable:

export NDK_ROOT=/Users/alex/android-ndk-r8b

Next, create an android project. In Terminal, in the same directory as before:

./ --box2d

The –box2d parameter makes sure to include the Box2D library.
You will be asked three questions:
Identify your project

Input package path. For example: org.cocos2dx.example

Choose what Android version you want. It will list what SDKs are available on your system. If you don’t have any, install one.

Now cocos2d-x supports Android 2.2 or upper version
Available Android targets:
id: 7 or "Google Inc.:Google APIs:10"
     Name: Google APIs
     Type: Add-On
     Vendor: Google Inc.
     Revision: 2
     Description: Android + Google APIs
     Based on Android 2.3.3 (API level 10)
      * (usb.jar)
          API for USB Accessories
      * (maps.jar)
          API for Google Maps
     Skins: WVGA854, WQVGA400, HVGA, WQVGA432, WVGA800 (default), QVGA
     ABIs : armeabi
input target id:

Last, give a name/directory for your project.

input your project name:

Now, test this to make sure it compiles

cd testgame

Move the necessary Android files

The XCode template only copied enough over for iOS devices. We are going to include the Android files as well.

  • Move the <COCOS2DX_ROOT>/testgame/ folder to the iphone project folder, next to ios. Rename it android.
  • Copy the <COCOS2DX_ROOT>/external/Box2D folder into <IPHONE_PROJECT>/libs/, replace what is there.
  • Copy the <COCOS2DX_ROOT>/cocos2dx folder into <IPHONE_PROJECT>/libs/, replace what is there.
  • Copy the <COCOS2DX_ROOT>/CocosDenshion/android folder into <IPHONE_PROJECT>/libs/CocosDenshion/
  • Copy the <COCOS2DX_ROOT>/extensions folder to <IPHONE_PROJECT>/libs/, replace what is there.

Change the Android files to fit the new location

We moved the relative location of the cocos2dx folder for the Android project. Instead of going two directories back, the cocos2dx folder is now one directory back and in the libs folder. In <IPHONE_PROJECT>/android/, change line 40:


And update the LOCAL_C_INCLUDES on line 13 to include Box2D:

LOCAL_C_INCLUDES := $(LOCAL_PATH)/../../Classes 

Next, in android/jni/, add a LOCAL_C_INCLUDES path to Box2D and change “$(call import-module,external/Box2D)” to “$(call import-module,Box2D)”. The result should look like this:

Test and run

Everything should be set up! Build the project from XCode to test iOS. Use these commands to build for android from the command line (in the new android directory)

./ clean
ant debug
adb install -r bin/testgame-debug.apk
adb shell am start -a android.intent.action.MAIN -n com.boldit.testgame/.testgame

The first two commands clean and build the cpp into java. The `ant` command builds a debug apk for us. The last two commands install and run the apk, respectively.


This error:

Android NDK: /Users/alex/testgame/testgame/android/../libs/cocos2dx/platform/third_party/android/prebuilt/libcurl/ Cannot find module with tag 'Box2D' in import path    
Android NDK: Are you sure your NDK_MODULE_PATH variable is properly defined ?    

was caused because Box2D was not completely configured.

9 Responses to “Cocos2d-x Box2D iOS/Android Hybrid Tutorial”

  1. Gustavo

    Hi Alex, thanks for the tutorial , i have some nightmare with the shared workspace in cocos2dx too , i actually upgraded to least cocos2dx-v2 , and have some issues with the environment.

    This is my configuration
    export PATH=$PATH:$NDK_ROOT

    Im receiving :

    Android NDK: jni/ Cannot find module with tag ‘CocosDenshion/android’ in import path
    Android NDK: Are you sure your NDK_MODULE_PATH variable is properly defined ?

    Im using ndk8 , did you have some similar problem?

    • alex

      I don’t remember getting that issue. Make sure that folder is in its correct place and it is defined in if necessary.

  2. farhad

    We are using cocos2d-x 2.0.1 , there are no extension folder. so what to do………

    • alex

      The extensions folder is in the cocos2d-x root, you may have to check one directory up.

  3. Innich

    I had the same problem.
    Forgot to change COCOS2DX_ROOT=”$DIR/../libs”
    Excellent tutorial btw, thanks!

  4. Farhad

    Thanks for your great tutorial , it works like a charm in my game with cocos2d-x v2.0.1

    but as now, i want to build the game with cocos2d-x c2.0.4 but it is showing some error as below……..
    “/Users/Rakib/cocos2dx-2.0.4/testGame/testGame/android/../libs/cocos2dx/platform/third_party/android/prebuilt/libtiff/ Cannot find module with tag ‘extensions’ in import path
    Android NDK: Are you sure your NDK_MODULE_PATH variable is properly defined ? ”

    can you help me out, please???????????????

    • alex

      Sorry, I haven’t tried the latest version of Cocos2d-x. I created this tutorial because the most recent previous one was a year ago. These things seem to get out of date pretty quick.

  5. federico

    When you say “/libs/, change line 40:”, i though you mean the /android folder, not the libs…

    However, I get some errors, like:
    error: undefined reference to ‘CGameManager::~CGameManager()’
    error: undefined reference to ‘CBox2dFactory::factory’

    • alex

      Thank you. I’ve updated the article.

      As for the errors, I’m not sure. It has been a while, I hope you’ve moved past these.