There are many things that an Android C++ Cocos2d-x Game Developer needs to know in order to successfully develop, test and publish a game.
The following are 13 things that I believe every Android C++ Cocos2d-x Game Developer must know. Think of this article as more of an overview or cheatsheet. To master these topics, you will likely need to do some more research. But, master each of these and your life as an Android game developer will go much more smoothly.
Need help setting up an Android Cocos2d-x C++ Eclipse development environment. Then checkout this article here. In the future I probably will change over to Android Studio, but at the time of this article, Android Studio is not ready for developing, testing and publishing C++ games as a complete process.
The Cocos Console
The cocos console is designed to make your life easier. It is used to create a new project, compile, package, code sign and deploy your game. More details can be found here on how to use the cocos console.
On Android, the command:
cocos run -p android -m debug
will compile, package, deploy and run your app on an attached Android device or simulator.
For a while, I really wanted to get Eclipse to work well with a C++/Java hybrid cocos2d-x project. I didn’t want to directly use the command line tool to build and run my games. But I have spent countless hours debugging strange issues with Eclipse and Cocos2d-x compatibility.
So now I spend more time with the terminal command line and less with eclipse. Maybe in the future Android Studio will be a stable development solution. Or maybe I should look more into Visual Studio 2015’s Android support. But for now I do most of my development in Xcode and the command line gets the job done for Android.
The Android Debug Bridge (adb) Command Line Tool for Debug Logging
Android provides great tools for working with Android apps. They are simple to use and can be very helpful. The Android Debug Bridge is just one example. The adb tool is located in your Android SDK folder at <sdk>/platform-tools/adb.
The adb command line tool is essentially part of a client-server solution that enables connecting to Android devices or simulators to debug and perform other tasks. It has many features that are described here.
One must-know feature is logcat debug logging with adb. The command line syntax is like this:
adb logcat
You can also add options and filters as described here.
It can be really helpful if you add the<sdk>/platform-tools folder to your system path variable. I do this on Mac by adding the lines below to my .bash_profile in my home directory. Then you can type adb in any folder.
export PATH=/MY_PATH_TO_SDK/android-sdk-macosx/tools:$PATH
The AndroidManifest.xml File
There is a lot going on in the AndroidManifest.xml file. But for Cocos2d-x developers, here are the important highlights.
The file is located in your proj.android folder inside of your Cocos2d-x project.
You must set your package, versionCode, versionName, minSdkVersion you intend to support, and setup activities for things like Google Play Game Services or third party ad networks if you want to use such things.
The package is how your app is indexed on Google Play or the Amazon Appstore. e.g. com.heyalda.myAppName.
The versionCode is an integer that must be incremented for each build that you publish.
The version name is the string that will be displayed to the users indicating the version of the app.
The minSdkVersion is the minimum android API level that you want your game to support. This is an integer number, and it is NOT the Android version number. This can be confusing. e.g. I choose to support a minimum APU level of 13. That is the number I set for minSdkVersion. API level 13 is equal to Android version 3.2.x. So devices that don’t have at least Android version 3.2.x cannot install my games.
You also can define your targetSdkVersion, but if you leave it blank then the targetSdkVersion is automatically defined to be equal to the minSdkVersion. More info on this here.
The AndroidManifest.xml is also where you add permissions such as network access, read and write access to external storage, internet access, etc. If you don’t enable a permission in the AndroidManifest.xml file that your app needs, then your app won’t work properly. e.g. want to show ads in your app, then your will likely need the Internet permission. The documentation from third party SDK’s will tell you what you need for them to work.
The Android Command Line Tool
The command line tool called android is another important tool that is packed full of functionality; most of which is executed behind the scenes for you because the cocos command line tool uses the android command line tool.
The android command line tool is located in the<sdk>/tools folder.
One important task for you to know about that requires this tool is to update your Android SDK or install additional components. This is done by executing the following via command line.
android update sdk
This will launch the Android SDK Manager. From there you can see what is currently installed and install/uninstall various versions of the SDK as well as sample code and other sdk components.
It can be really helpful if you add the<sdk>/tools folder to your system path variable. I do this on Mac by adding the lines below to my .bash_profile in my home directory. Then you can type android in any folder.
export PATH=/MY_PATH_TO_SDK/android-sdk-macosx/tools:$PATH
Nexus Firmware Images
You do have a Nexus device to test on, don’t you? The Nexus family of Android devices are designed and developed by Google (albeit manufactured by various electronics manufacturers). These devices are usually the first to get Android updates distributed to the public and in my opinion are the first device one should buy for testing Cocos2d-x games.
To make testing even smoother, Google provides the historical major versions of firmware for these devices. These can be downloaded here. The re-imaging of a device is fast. For a 2013 Nexus 7, you can have a device with a specific Android version ready to test in minutes.
So there is no reason that a developer cannot test on various Android SDK versions, even if the test device budget is low.
The src Folder
The proj.android/src folder contains your java source code. This is where you can add your own java source packages or modify your games AppActivity.java as needed. For many Cocos2d-x developers, this might never be necessary. But if you add in app purchases, ads, leaderboards, or other third party components to your game, then getting into some Java code likely will be necessary.
The Java Native Interface (JNI)
The Java Native Interface is a mechanism to enable java code to communicate with native code, e.g. Java byte code to communicate with code that speaks the device’s CPU instruction set. This is needed when you have Java code, such as a Google Play Leaderboard, and C++ Cocos2d-x code, that need to communicate. There are special data types for this communication. This is something that at one point or another you likely will want to learn more about.
The res Folder
The proj.android/res folder is the location of your game icons and a values folder that holds various xml files. You will want to dig around in the res folder to update your game icons before publishing. If you add Google Play Game Services to your game, you will need to add the game-ids.xml file to this location so that Google Play Game services can read your app_id from that file.
The Android.mk File
Located in the proj.android/jni folder, the Android.mk file tells the c++ compiler how to process, compile and link your game. The most common change you will need to make there is to define where to find your source code header files (.h) and where to find the source files.
The header files search path is defined by LOCAL_C_INCLUDES and the source files are defined by LOCAL_SRC_FILES and are relative to the $(LOCAL_PATH), which is the location of the Android.mk file.
These can be initialized in the Android.mk file like this:
LOCAL_SRC_FILES := hellocpp/main.cpp
LOCAL_C_INCLUDES := $(LOCAL_PATH)/../../Classes
And then you can add additional folders like this:
LOCAL_C_INCLUDES += $(LOCAL_PATH)/../../Classes-Android
FILE_LIST := $(wildcard $(LOCAL_PATH)/../../Classes-Android/*.cpp)
LOCAL_SRC_FILES += $(FILE_LIST:$(LOCAL_PATH)/%=%)
Or individual files like this:
LOCAL_C_INCLUDES += $(LOCAL_PATH)/../../Classes-Android/MyClass.h
LOCAL_SRC_FILES += $(LOCAL_PATH)/../../Classes-Android/MyClass.cpp
The ../../ is used to step out of the folder that contains the Android.mk file to get to a relative path, where each ../ steps you out one folder depth, just like on a command line.
The build.xml File
Located in the proj.android/ folder, the build.xml file is generated by and updated by the android command line tool and the adb command line tool. But when I rename a project, I manually change its name in the build.xml file. Not certain if this is necessary, or what the impact is, but I have done so for the many Cocos2d-x games that I have published that needed to be renamed.
Code Signing and the ant.properties File
Code signing for Android is a simple process when you have things setup properly.
First you need to create your debug and release keystore on your computer.
Then in the ant.properties file you need to add the following so that when the cocos console executes the ant build process your keystore will be used to sign the app.
key.alias.password=YOUR_PASSWORD_HERE
key.store.password=YOUR_PASSWORD_HERE
key.store=/YOUR_PATH_TO_KEYSTORE/.android/release.heystore
key.alias=YOUR_KEYSTORE_ALIAS_NAME
Info about how to create your keystore using the keytool can be found here.
How to Structure Your Resources Folder
The Resources folder in the Cocos2d-x project is where you will want to put your image files, sound files, 3D models and any other assets that your game will use. These will be automatically copied into the proj.android/assets folder for you. Don’t try to put anything into the assets folder manually, because it is deleted each time you build your project.
It is a good practice to use folders to organize asset files in the Resources folder. But if you do this you will need to reference files by the relative path to the Resources folder. e.g for a file located at ./Resources/soundFiles/sound.wav you would refer to this file as “soundFiles/sound.wav” in your code.
Packaging for Distribution
Each time you run your game using cocos run -p android -m release you will build, package, and code sign your game.apk package. The .apk package is located at MY_PROJECT_FOLDER/bin/release/android/MY_GAME.apk.
Proper code signing assumes that you have your Android keystore setup properly and that you configured your ant.properties file for code signing as described above.
So after you have fully tested the release build of your app, you can upload that .apk file to either Google Play or Amazon to publish your game.