Cocos2d-x: Starting Cocos2d-x (Android) Initial setup and troubleshoot on Mac OS X

Following steps will help you to avoid various errors on first time setup of Cocos2d-x in Mac OS-X. I believe the procedure will be same for other Platforms (Win / Linux).

Some of the errors on first time Cocos2d-x setup:

1. Error: Please define NDK_ROOT

2. Error: APP_PLATFORM android-14 is larger than android:minSdkVersion 8 in ./AndroidManifest.xml

3. Error: can’t resolve org.cocos2dx or Cocos2dxActivity

4. Error: make *** obj/local/armeabi/libgame_logic.so error 1

Step 1: Download ADT Bundle for Mac

There are not much of other options. Android studio is still in Early access preview version and even if its stable, the C/C++ component of IntelliJIdEA is not really in a strong position. This left us to use ADT Bundle for developing games using Cocos2d-x.

Step 2: Download Android SDK

ADT bundle already has the latest Android SDK version. I am guessing you already know how to update / download various SDK version. I am using: Android API 10

Step 3: Download Cocos2d-x

Different versions of Cocos2d-x have some REALLY MAJOR differences. One of them is the Framework folder structure. Which means, if I am referring to you to follow a path to find a folder, you may not get the folder on that path. That is why I would suggest you to use same version of Cocos-2dx as of mine for now. I am using: cocos2d-x-2.1.4

Step 4: Download Android NDK

Any version of NDK should work. I am using: android-ndk-r8e

Step 5: Set Android SDK and NDK path to Cocos2d-x

• Open ~/cocos2d-x-2.1.4/create-android-project.sh file in a text editor.
• Set NDK_ROOT_LOCAL and ANDROID_SDK_ROOT_LOCAL constants with the appropriate value. After the change, it should look like

#!/bin/bash
# This script should be called by create-android-project.bat
# or should be runned in linux shell. It can not be runned under
# cygwin.
# Don't modify the script until you know what you do.

# set environment paramters
NDK_ROOT_LOCAL="/Users/Shahab/android-ndk-r8e"
ANDROID_SDK_ROOT_LOCAL="/Users/Shahab/android-sdk-macosx_20"

NEED_BOX2D=false
NEED_CHIPMUNK=false
NEED_LUA=false

Step 6: Add Android SDK and NDK path to Mac OS X .bash_profile

• Open Terminal and write: nano .bash_profile
• Add Android SDK and NDK root path in a Constant variable.
• Then Add the Constants to the Path. After the change it will look like

export JAVA_HOME=/System/Library/Java/JavaVirtualMachines/1.6.0.jdk/Contents/Home
export NDK_ROOT="/Users/Shahab/android-ndk-r8e"
export SDK_ROOT="/Users/Shahab/android-sdk-macosx_20"
export SDK_PLATFORM_TOOLS=$SDK_ROOT/platform-tools
export SDK_TOOLS=$SDK_ROOT/tools
export PATH=$PATH:$JAVA_HOME/bin:$NDK_ROOT:$SDK_PLATFORM_TOOLS:$SDK_TOOLS
#echo $PATH

Step 7: Create an Application

• Open Terminal and goto: ~/cocos2d-x-2.1.4/
• Run command: ./create-android-project.sh

Example:

~$ cd /Users/Shahab/Cocos2D/cocos2d-x-2.1.4/
~$ ./create-android-project.sh

Step 8: Project Configuration

Package Name
Enter your reverse domain name with the application name
My application name is: SuperGame
My domain name: cloudtea.ms

use global definition of NDK_ROOT: /Users/Shahab/android-ndk-r8e
Input package path. For example: org.cocos2dx.example
ms.cloudtea.supergame

Select Android version
A comprehensive list should be generated automatically. Enter the id of the Android version you want to use. Scroll through upward to see the generated list and you will find the id. I am using Android API 10; so my input will be: 3

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

Project Name
Enter your Project name

input your project name:
SuperGame

Now, you should see a folder inside cocos2d-x-2.1.4 named “SuperGame”

Step 9: Project Configuration

• Open Terminal and goto: ~/cocos2d-x-2.1.4/SuperGame/proj.android
• Run command: ./build_native.sh

~$ cd /Users/Shahab/Cocos2D/cocos2d-x-2.1.4/SuperGame/proj.android 
~$ ./build_native.sh 

It may take a while.
You should see the progress in the terminal (something is happening 🙂 hold tight!)

Step 10: Configure ADT

• Open ADT
• Help Menu => Install New Software…
• form Work with: dropdown select:
  Juno - http://download.eclipse.org/releases/juno

or,
Kepler - http://download.eclipse.org/releases/kepler

based on your Eclipse version
wait for a while. A list will be loaded

• Expand Programming Languages from the list below
• Put Check mark on the followings

For Juno:
C/C++ Development Tools
C/C++ Development Tools SDK
C/C++ Unit Testing Support
CDT Visual C++ Support
Eclipse Java Development Tools
Unified Parallel C (UPC) Support
Unified Parallel C Berkeley UPC Toolchain Support
XL C/C++ Compiler Support

For Kepler:
put check marks on all “C/C++” prefix variance
except: “C/C++ Autotools support”

• hit Next => Next => I accept the terms of the license agreement => Finish
• After downloading and installing the software, ADT will ask you to restart. Restart ADT

Step 11: Import Project

• File => Import => Android => Existing Android Code Into Workspace
• Browse ~/cocos2d-x-2.1.4/SuperGame/proj.android => Open => Finish

Step 12: Add C/C++ Nature

• Right click the project
• New => Other => C/C++ => Convert to a C/C++ Project (Adds C/C++ Nature) => Next
• From Project type: select MakeFile project
• From Toolchains: select –Other Toolchain– => Finish

Step 13: Configure Build Command

• Right click the project => Properties
• From C/C++ Build:
• (right side) Uncheck use default build command
• Enter following value in Build command
  bash ${workspace_loc:/SuperGame}/build_native.sh NDK_DEBUG=1 V=1

Note that: I used “SuperGame”, use your own game name (if different from mine)

• Apply; Do not press OK yet

From left menu, expand C/C++ General => Code Analysis => (right side) Check Use project settings

• Uncheck all the checked Problems below

(These will produce irrelevant error for Cocos-2dx, and prevent the code from run, so uncheck all)

• Apply; Do not press OK yet
• From left menu, C/C++ General => Paths and Symbols => (right side) select Tab: includes
• Click Add => File system…
• Browse: ~/android-ndk-r8e/platforms/android-9/arch-arm/usr/include

=> OK

following steps will enable the C/C++ code completion feature of Cocos2d-x classes in ADT

• Click Add => File system… again
• Browse: ~/cocos2d-x-2.1.4/

=> Open => OK

• Select Tab: Source Location
• Click Link Folder
• Check List to folder to the file system
• Browse: ~/cocos2d-x-2.1.4/SuperGame/Classes

=> Open => OK

Similarly add the cocos2dx path

• Click Link Folder
• Check List to folder to the file system
• Browse: ~/cocos2d-x-2.1.4/cocos2dx

=> Open => OK

Similarly add the CocosDenshion path

• Click Link Folder
• Check List to folder to the file system
• Browse: ~/cocos2d-x-2.1.4/CocosDenshion

=> Open => OK

• Done! hit Apply => Yes on rebuild project message =&git; OK

Step 14: Troubleshoot 1: Copy lib folder

• Copy lib folder from:
  ~/cocos2d-x-2.1.4/cocos2dx/platform/android/java/src/org/cocos2dx
• Paste: ~/cocos2d-x-2.1.4/SuperGame/proj.android/src/org/cocos2dx
• ADT => Project => Clean

Step 15: Troubleshoot 2: Add NDK_ROOT in build_native.sh

• Open ~/cocos2d-x-2.1.4/SuperGame/proj.android/build_native.sh in a text editor
• Add NDK_ROOT constant; finally It will look like

# paths

export NDK_ROOT="/Users/Shahab/android-ndk-r8e"

if [ -z "${NDK_ROOT+aaa}" ];then
echo "please define NDK_ROOT"
exit 1
fi

Step 16: Troubleshoot 3: Add APP_PLATFORM

• Open ADT => Expand Project SuperGame => jni => Application.mk
• It should look like following

APP_STL := gnustl_static
APP_CPPFLAGS := -frtti
APP_PLATFORM := android-8

Step 17: Troubleshoot 4: Copy assets in Resources

• Do not copy your drawable/png files in ADT => assets
• Instead, copy them into: ~/cocos2d-x-2.1.4/SuperGame/Resources
• ADT => Project => Clean

Step 18: Troubleshoot 5: Use Java version 1.6

• Right click on the project => Properties
• Java Compiler => Check Enable project specific settings
• select 1.6 from Compiler compliance level:

Step 19: Troubleshoot 6: Declare your classes in Android.mk

• Make sure you included all of your cpp source class files in Android.mk file
• Open ADT => Expand Project => jni => Android.mk
• For example, I have added (MainMenuScene.h and MainMenuScene.cpp) files in my project. You only need to add the *.cpp classes
• After the changes this will look like the following

<code>LOCAL_SRC_FILES := hellocpp/main.cpp \
                   ../../Classes/AppDelegate.cpp \
                   ../../Classes/HelloWorldScene.cpp \
                   ../../Classes/MainMenuScene.cpp

N.B: Be careful: add the Src file names in Alphabetical order

Happy Coding!!