Cocos2D-X Tutorial for iOS and Android: Getting Started

Hello, Cocos2D-X for Android!

Now let’s do a “Hello, World” Cocos2D-X tutorial for the Android platform, just as you did for iOS.

You will need to do this via the command line, however, since there are no Cocos2D-X project templates available via the Eclipse IDE at the moment. (You know what? This would be a great open source project candidate, if you are so inclined :])

The $COCOS2DX_HOME directory contains a shell script named create-android-project.sh that you will use to generate the android project.

But, before launching this shell script for the first time, you need to make a tiny customization at the top of the above file:

# set environment paramters
NDK_ROOT_LOCAL="/home/laschweinski/android/android-ndk-r8d"
ANDROID_SDK_ROOT_LOCAL="/home/laschweinski/android/android-sdk-linux_86"

Modify these above lines so that the NDK_ROOT_LOCAL variable points to the directory where you installed the Android NDK ($NDKROOT) and ANDROID_SDK_ROOT_LOCAL points to the place where you installed the Android SDK.

Now run the create-android-project.sh script from the command line and you will get several prompts as to various input values. These prompts will ask you to provide the below information:

1. The first prompt will ask you for the “Input package path”. This is the package name that will be used for java code production. You can use reversed domain notation here (similar to an iOS bundle ID) – something like com.yourdomain.samplecocos2dxandroid (remember to replace com.yourdomain with the reverse domain notation for your actual domain)
2. Next, you will get a list of available Android APIs and their ids. Depending on what’s installed on your machine, the list will vary. But the prompt at this stage simply asks for the Android API level your app will support and you can use the id for the last item on the list that’s a Google API.
3. Finally, you have to provide the project name. Call it samplecocos2dxandroid.

The command-line output from the above process will look something like the following:

bash-$ ./create-android-project.sh
Input package path. For example: org.cocos2dx.example
org.jymc.samplecocos2dxandroid
. . . 
Available Android targets:
----------
. . .
----------
id: 25 or "Google Inc.:Google APIs:17"
     Name: Google APIs
     Type: Add-On
     Vendor: Google Inc.
     Revision: 2
     Description: Android + Google APIs
     Based on Android 4.2.2 (API level 17)
. . .
input target id:
25
input your project name:
samplecocos2dxandroid
Created project directory: 
/Users/jymen/development/cocos2dx/samplecocos2dxandroid/proj.android
. . .
Added file /Users/jymen/development/cocos2dx/samplecocos2dxandroid/AndroidManifest.xml
Added file /Users/jymen/development/cocos2dx/samplecocos2dxandroid/build.xml
Added file /Users/jymen/development/cocos2dx/samplecocos2dxandroid/proguard.cfg
bash-$ 

Pay attention to the Created project directory: line towards the end of the script output. That’s where your Android project has been created by the script. The project location (/Users/jymen/development/cocos2dx/samplecocos2dxandroid in the above example) will be referred as $PROJECT_HOME from now on.

Note: Do not try to move the project from that location to a different location. At least one of the scripts you’ll work with in the next section will not work if you do.

Building the Project

There are two steps to building the project – compiling the C++ code with a command line script, and compiling the Java code with Eclipse.

But, before compiling, you need to define NDK_ROOT parameter so it points to your $NDKROOT directory. Open the $PROJECT_HOME/proj.android/build_native.sh shell script and add the following line at the top of the file:

# paths
NDK_ROOT="/home/laschweinski/android/android-ndk-r8d" 

Modify the above line so that the NDK_ROOT variable points to the directory where you installed the Android NDK ($NDKROOT).

To compile the C++ code, switch to the $PROJECT_HOME/proj.android folder via the command-line and issue the following command:

./build_native.sh 

Note: If at this point you are getting the message “please define NDK_ROOT” you must ensure that you specified correctly the root to your Android NDK directory in the above step.

You should see some output similar to the following in response to the above command:

Gdbserver      : [arm-linux-androideabi-4.4.3] libs/armeabi/gdbserver
Gdbsetup       : libs/armeabi/gdb.setup
Compile++ thumb  : cocos2d <= CCConfiguration.cpp
Compile++ thumb  : cocos2d <= CCDrawingPrimitives.cpp
:
:
:
Compile++ thumb  : cocos2d <= CCTileMapAtlas.cpp
Compile++ thumb  : cocos2d <= CCTouchDispatcher.cpp
Compile++ thumb  : cocos2d <= CCTouchHandler.cpp
Prebuilt       : libstlport_static.a <= <NDK>/sources/cxx-stl/stlport/libs/armeabi/
SharedLibrary  : libcocos2d.so
Install        : libcocos2d.so => libs/armeabi/libcocos2d.so
Compile++ thumb  : cocosdenshion <= SimpleAudioEngine.cpp
Compile++ thumb  : cocosdenshion <= SimpleAudioEngineJni.cpp
SharedLibrary  : libcocosdenshion.so
Install        : libcocosdenshion.so => libs/armeabi/libcocosdenshion.so
Compile++ thumb  : game_logic <= AppDelegate.cpp
Compile++ thumb  : game_logic <= HelloWorldScene.cpp
SharedLibrary  : libgame_logic.so
Install        : libgame_logic.so => libs/armeabi/libgame_logic.so
Compile++ thumb  : game <= main.cpp
SharedLibrary  : libgame.so
Install        : libgame.so => libs/armeabi/libgame.so

This builds the C++ Cocos2D-X libraries, and the C++ code for your project.

To build the Java code, you’ll create an Eclipse project – that’s way easier than working via the command-line :]

Start Eclipse and go to File\New\Other. Choose Android\Android Project from Existing Code, and click Next. Click Browse and select the $PROJECT_HOME/proj.android folder, as shown below.

Click Finish, and you now have a project!

Note: By default the Android Build Target is 2.2 but change it to use the latest version. To do it select Project\Properties from the main menu, choose Android from the list on the left and select Android 4.2.2. Be sure that you have configured an AVD with Target Name 4.2.2. If you need more information, check out the Getting Started with Android Development tutorial.

At this point the project might have some errors but don’t be affraid, they are pretty easy to fix:

One of the errors rises because Eclipse can’t find the resource “@drawable/icon” so, expand the project tree on the left, open AndroidManifest.xml and change to the AndroidManifest.xml view so you can see the plain text. Look for the following line of code:

<application android:label="@string/app_name"
android:icon="@drawable/icon">

and change it by the correct icon name:

<application android:label="@string/app_name" 
android:icon="@drawable/ic_launcher">

And, before you close AndroidManifest.xml, modify android:minSdkVersion to be:

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

and Save the file.

The second error rises because Eclipse can’t find some Cocos2D-X Java classes. Select Project\Properties from the main menu and choose Java Build Path from the list on the left. In the Source tab click on Link Source and Browse to the following directory

$COCOS2DX_HOME/cocos2dx/platform/android/java/src/

where $COCOS2DX_HOME is the directory where you installed the Cocos2D-X resources. In Folder name write cocos2dx-src, click Finish and OK.

Now the project has no errors, it was easy right?

You can now run it. Right click the project in the tree on the left and select Run As\Android Application. The AVD (Android Virtual Device) will launch showing the Hello, Cocos2D-X project (maybe, if it doesn’t work keep reading below):

If the application does not launch on the emulator and LogCat Eclipse view shows the error java.lang.IllegalArgumentException: No config chosen, it’s due to an issue with OpenGL ES 2.0 in latest AVD Target versions. To solve it you must take two steps:

1) Go to the Android Virtual Device Manager, select the AVD you are using and click Edit. Then make sure the Use Host GPU checkbox is checked, as shown below:

2) Now open samplecocos2dxandroid/cocos2dx-src/org.cocos2dx.lib/Cocos2dxActivity.java, look for init() method and add:

this.mGLSurfaceView.setEGLConfigChooser(8, 8, 8, 8, 16, 0);

before:

this.mGLSurfaceView.setCocos2dxRenderer(new Cocos2dxRenderer());

Now try running it again – and hopefully it should work this time.

For more details about configuring an Android Virtual Device, check out the Getting Started with Android Development tutorial.

Congrats, you now have a “Hello, World” project running on both iOS and Android!