Setting up Cocos2d-x for Android Game Development

As cocos2d-x is ported to C++, now you can develop game for both iOS and Android platform. In the previous tutorial I have discussed on how to setting up cocos2d-x game engine in OSX for iOS game development. Now, in this tutorial I will discuss on Android game development using cocos2d-x.

This tutorial asumes that you have a fully functional Android development environment using Eclipse IDE and Android SDK. If you do not, please go through  "Setting up Android Development Environment"  from Android Official Developers Site first, which provides a step by step procedure on setting up a dedicated Android Application Development environment and install various prerequisite softwares.

After completing the previous steps you are now all set to follow the described steps later in this tutorials. Develop Android games in cocos2d-x is some how complex comparison to iOS game development. The most complex and trickiest part for Android Game development is to set up the development environment for Android. So, please pay full attention when setting up the environment for Android.

Setting up Eclipse for Cocos2d-x

To develop Cocos2d-x project in  Eclipse we need to install some plugins for C/C++ development as Cocos2d-x is developed using C++. Open the Eclipse and perform the following steps:

1. From the Eclipse IDE main toolbar, go to Help/Install New Software 


2. Open the Work with combo box and select the item containing your Eclipse version name. For my workstation it is juno. 


3. Find Programming Languages in the plugin tree and open it. 


4. Select CDT plugins and check the installation of the following components.
   

Setting up the Android NDK

1. Android products are extensively developed in Java but on the other hand, cocos2d-x is written in C++. To develop Android based 2d games in  cocos2d-x you need to installed Android NDK which supports to develop android application in C/C++. First download the latest Android NDK from  here. 


2. Unzip the Android ndk at your preferred location. I will refer the location  as $NDK_PATH.

Create a Project in Cocos2d-x

1. If you already download cocos2d-x at your environment then go tho step 4, otherwise, download the Cocos2d-x library form here. You can visit the Cocos2d-x download page and installed any stable version. I have installed cocos2d-2.1rc0-x-2.1.2 version for this tutorial. Right now this is the stable version for the Cocos2d-x. You can install previous versions at your choice. For the latest release there is some changes in the core library. So, be careful when you select other versions.


2. Unpack the ZIP file to a location of your choice. I recommend putting it in an easily accessible place. Rename it as you wish but it would be better to just leave it be once you unpacked it. For this tutorial,  I will refer the path as $COCOS2DX_PATH. You should replace this variable with your cocos2d-x folder location.


3. Now open up the Terminal and change the directory to the Cocos2d-x Root using the cd command.
   
   cd $COCOS2DX_PATH


4. In the $COCOS2DX_PATH directory there are files named create-android-project.sh and create-android-project.bat If your environment is Windows use create-android-project.bat and if you use Mac OSX then use create-android-project.sh As my workstation is Mac OSX, I have used create-android-project.sh to create a sample project in cocos2d-x. Before run the script you need to modify the create-android-project.sh file a bit. 


5. Open the script file using your preferred text editor and go to the top of the script. You will find two declared variables named  NDK_ROOT_LOCAL and ANDROID_SDK_ROOT_LOCAL. By default these variables are set to some test values. Modify these above lines so that the NDK_ROOT_LOCAL variable points to the directory where you installed the Android NDK ($NDK_PATH) and ANDROID_SDK_ROOT_LOCAL points to the place where you installed the Android SDK.
   
   
   # set environment paramters
   NDK_ROOT_LOCAL="YOUR_ANDROID_NDK_PATH" ANDROID_SDK_ROOT_LOCAL="YOUR_ANDROID_SDK_PATH"


6. Now run the create-android-project.sh using the Terminal. To do so, open the Terminal and run the following command.
   
   ./create-android-project.sh
you will get several prompts as to various input values. We’ll run through the prompts and what you need to input one-by-one:
• 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.samplegame (remember to replace com.yourdomain with the reverse domain notation for your actual domain) 


• 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. 


• Finally, you have to provide the project name. Call it SampleGame. 
7. The above command will create a cocos2d-x game project inside the $COCOS2DX_PATH folder. Find the directory named after your entered game project name. If everything ok you will find a folder named after your game name.

Build the Game Project

Until now we are created a project in cocos2d-x using the template provided by cocos2d-x. Now we need to build the project to run the Application in Android simulator or real devices. First we build the application using command from Terminal. Later we incorporate our build procedure with in the Eclipse IDE and build from the IDE.

To build the Android application we run the build_native.sh script file which is located inside the Project folder. For SampleGame, go to $COCOS2DX_PATH/SampleGame/proj.android and find the build_native.sh file.

Open the build_native.sh file and add a variable named NDK_ROOT which points to the place of Android NDK directory. To do this add the following line at the top of the file:

export NDK_ROOT="$NDK_PATH"

Run the following command in the Terminal.

./build_native.sh

You should see some output for the command and this will build the C++ Cocos2d-x library and C++ codes in your project.

Now to build the java codes in the project we need to create an Android Project using Eclipse IDE. 

Start Eclipse and  got to  File\New\Other. Select Android\Android Project from Existing Code. Select Next.

Now we need to import the project directory by browsing the Project folder to $COCOS2DX_PATH/SampleGame/proj.android. Click finish. This will import the android project to your Eclipse workspace. 

The Android project may show some error like "cannot resolved libcocos2dx path" when it tries to build the project. This happens because Android compiler does not find cocos2d-x library in the workspace. To resolve this issues import the cocos2d-x project in the workspace. Go to File and select Import .  Then select "Android\Existing Android Code into Workspace".

Next, browse the cocos2d-x library for the Android to $COCOS2DX_PATH/cocos2dx/platform/android  directory and select finish.

Build the Android Project and Run the project by right click the project in the left tree, and select Run As\Android Application. The AVD (Android Virtual Device) will launch showing the Hello, Cocos2D-X project!

Build Cocos2d-x Project from Eclipse IDE

Upto now we have created a cocos2d-x game, build the game in command line and run the application in Android Simulator. But, build the project in  command line and run the application in Eclipse IDE is some how uncomfortable. So, now we modify our project set up so that we can build the project and can edit the project in our favourite Eclipse IDE.

Select the samplecocos2dxandroid project in the left tree, and select File\New\Other from the menu and then, C/C++\Convert to a C/C++ Project (Adds C/C++ Nature) from the dialog, as shown below:

Edit the Project options and toolchains for the C/C++ project. As we use a makefile project for the cocos2dx project we select Makefile Project options and select "Other toolchains" option which we edit later. Please pay extra caution when you select Project type and Toolchains. Then select Finish.

Eclipse may ask you if you want to open the C/C++ perspective, just click No if this occurs. The next step is to change the project settings to specify how to run our make command. In the left tree, right click the SampleGame project, select Properties, and select the C/C++ build section. Unselect the default build command option and edit the Build command field to
"bash ${workspace_loc:/SampleGame}/build_native.sh". Select Apply.

Now you can build the cocos2d-x project using Eclipse IDE. Select Project\Build All form the main menu, and you’ll see the C++ make run in the Eclipse console. Finally Run the Application using Run As\ Android Application. 

Resolve Eclipse IDE issues for Compile Cocos2d-x Project

There are still some error and warnings in the android project. Open the main.cpp file from jni/helloworl folder. You will face some error in the file. These are occurring because we do not have the correct C++ include path specified yet. To do this, in the left tree, right click the SampleProject and select Properties\C/C++ General\Path and Symbols\GNU C++. 

Use the Add button to select the two directories shown below, then click Apply and OK.

$(NDK_PATH)/platforms/android-9/arch-arm/usr/include
$(COCOS2DX_PATH)/cocos2dx/include

Next, you need add source file location for the cocos2dx and Classes folder. To do so, right click on the SampleProject and go to Properties\C/C++ General\Paths and Symbols and select Source Location tab. Now, select Link Folder option check the Link to a folder in the file system checkbox, and browse to the Classes directory inside the $PROJECT_HOME folder. Click OK, then Apply and OK.

Similarly add cocos2dx project source location in the Link folder option for $COCOS2DX_PATH/cocos2dx folder.

Clean and build the android project. You may see errors as Eclipse IDE is slowing down when it resolves the issues. Wait for some time and build again. You can now successfully build and run the application from Eclipse IDE.

Whats next

Congrats, your wok environment is now all set to develop your 2d game using cocos2d-x for Android platform.