You will need for this guide:
- The Cocos2D-x 2.2.3 code
- Android SDK
- Android NDK
- Eclipse with Android Development Tools
Creating the project
First, let’s create a new project using the Cocos2D-x wizard. Download the Cocos code, unzip it somewhere on your hard drive, then open a Terminal and navigate to the tools folder:
Of course, you may have saved the unzipped folder somewhere else, so adjust the path accordingly.
From here, we need to run the create_project.py script that will make us a ready to use project structure that will have multiplatform support out of the box.
./create_project.py -project MyGame -package com.MyCompany.MyGame -language cpp
As you can see, you need to provide the script with a number of parameters:
-project [PROJECT NAME] – this is what you want to name your game
-package [PACKAGE NAME] – the package name will be used by the AppStore and the Play store to identify your application. The usual format for the package name is com.yourcompany.game_name. The yourcompany.com domain name doesn’t need to be real.
The script will then create your project in the cocos2dx/projects/[PROJECT NAME] folder.
You can now open your project folder and have a look at its contents:
The proj.android folder contains files specific to the Android version, the proj.ios to the iOS version and so forth.
An important folder is the Resources folder. This folder is shared by both Android and iOS. This is a both a good thing and a bad thing, but we’ll get to that later.
Another important folder is the Classes folder, this is where all the code you write will reside.
What you have now is a barebones game app that will display a label, an image and a button. Doesn’t sound like much, but it’s a good test to see if your setup is in working order.
Running on iOS
To build your game for iOS just open proj.ios/MyGame.xcodeproj project in Xcode, select the simulator and hit Run. You should see the test app in the iOS simulator.
Running on Android
To build your game for Android you will need to open the proj.android folder in the Terminal. From here you will run the build_native.sh script:
What this script does is compile the cpp files from your code and the Cocos2D-x code into a library that is then included in the Android build. The mechanics of what happens here are somewhat complex but fortunately we don’t have to touch them.
Getting back to where we were, remember this build_native.sh script, it is very important to run it before you test your Android build otherwise the Android build will not know about the new code. Because the process is so clumsy, we will write the code in XCode, run it and test it on iOS, and only occasionally run it on Android.
Now, another important file for Android is the proj.android/jni/Android.mk makefile. This file contains instructions to the compiler what to include when building the Android library. Whenever you add a new file, for example a new scene, you will need to add it to this file in the LOCAL_SRC_FILES section. The default values look like this:
LOCAL_SRC_FILES := hellocpp/main.cpp \ ../../Classes/AppDelegate.cpp \ ../../Classes/HelloWorldScene.cpp
If you were to add new scene, for example MenuScene.cpp, the new value should look something like this:
LOCAL_SRC_FILES := hellocpp/main.cpp \ ../../Classes/AppDelegate.cpp \ ../../Classes/MenuScene.cpp \ ../../Classes/HelloWorldScene.cpp
Don’t forget the trailing ” \”, this is what tells the Makefile interpreter that there are more values to add after the current line.
The big moment of testing your app on Android has arrived.
Actually running on Android
Open Eclipse and go to File > Import > Existing Android Code into Workspace and from here choose the proj.android folder in your project.
To run the project, right click in Eclipse on the project root and select Run as… > Android Application. That should do it.
Android emulator alternatives
As you probably know, the Android Emulator is a pain to work with. It’s slow to start, it’s slow to use, its performance is dreadful. A solution is to use an actual physical device. If you have one, absolutely test on it, but sometimes it’s difficult to have access to a large number of various physical devices.
If we can’t use the Android Emulator and we don’t have access to a physical device, what can we do? Fortunately, the fine people at Genymotion have released an Android emulator that doesn’t suck, runs in graphics accelerated mode, boots in seconds and it’s free for personal use. Download it, install a virtual device and boot it.
Unfortunately, you won’t be able to run your app just like that on it because you will need something called an “ARM translation installer” that can be downloaded from the XDA-developers forum. You don’t need Google Apps.
When you have this zip file, drop it on the running Genymotion virtual device it will ask for a confirmation and then install. Close the virtual device and start it again.
Now you can run your Android apps on the Genymotion virtual device, just make sure you start the emulator before hitting Run or Debug in Eclipse.