I recently got the cross-platform framework Cocos2d-x up and running on my computer for some programming tasks. The installation process proved quite challenging however, mainly due to the great lack of documentation. Therefore I decided to publish some complementary information to the official documentation here. I hope it will help!

The following process has been tested with Windows 8.1, Eclipse 4.4, Android SDK Tools 23.0.2, Android SDK Platform-tools and Build-tools 20, Android NDK32 r10 for Windows 64-bit and Cocos2dx 3.2.

Note 1: Make sure not to put any files in a path with spaces, as that will not be liked by Cocos2d-x. If you do include spaces, it will generate a path error when trying to build. E.g. “C:\Program is not recognized as an internal or external command, operable program or batch file.” when you try to use “C:\Program Files\”.

Note 2: If you put any files on the system partition (typically C:\) you will have to use administrator access whenever you want to change them. This means that you have to open any IDE you use (such as Eclipse) as an administrator. To avoid this, put all files on a drive that does not contain your Windows installation.

Note 3: For all C++ beginners, do not put “using namespace” in your header files. This may cause problems if the header is included in other files and suddenly starts overriding the default namespace in those files. See the following link for more info: http://stackoverflow.com/questions/5849457/using-namespace-in-c-headers/5849668#5849668

Installation instructions

1. Follow the instructions on the following link, but return here when you encounter a problem or a slow emulator: http://cocos2d-x.org/wiki/How_to_run_cpp-tests_on_Android.

Add your ANT_ROOT manually if the Cocos2d-x setup.py complains on invalid path (it will work).

To use “android list targets” and “adb install TestsDemo-debug.apk” in CMD/the terminal it may be necessary to add these programs to your path. You can use the command “export PATH=$PATH:$ANDROID_SDK_ROOT/tools:$ANDROID_SDK_ROOT/platform-tools” for this. Alternatively, the path will be: “SDK_ROOT/tools” for android and “SDK_ROOT/plattform-tools” for adb.

When running the Lua or CPP test on Cocos2d-x 3.2 with NDK 10, you will also encounter a compilation error when compiling the tests. This can be fixed by changing two lines in two files. See more info here: http://www.cocos2d-x.org/news/307 and the changes to make here: https://github.com/cocos2d/cocos2d-x/pull/7526/files (replace “long int tell();” with “ssize_t tell();” on line 90 in cocos/3d/CCBundleReader.h and change line 124 in templates/cpp-template-default/proj.android/.project to “<locationURI>PARENT-1-PROJECT_LOC/cocos2d/cocos/platform/android/java/src</locationURI>”). Note this however: “After fixing the compiling error, you will meet linking error when building lua test cases or new lua projects” And “We suggest you not to use NDK r10. Please use NDK r9d instead.”.

Note that the file name “TestsDemo-debug.apk” does no longer exist. Use “CppTests-debug.apk” instead. I.e. “adb install CppTests-debug.apk”. If you prefer to install the application on the SD card of your phone instead of its internal memory, use “adb install -s CppTests-debug.apk”. Using this last command will also help if you get a “No space left on device” error when using “adb install CppTests-debug.apk”. (assuming you have more space on your SD card than on your internal storage, the CppTests-debug.apk file is roughly 98 Megabytes)

For other problems, see the “Troubleshooting” section below.

2. If you got the cpp-tests working there are now two options:

If you intend to use Eclipse for development, look at the notes below and then go here: http://cocos2d-x.org/wiki/How_to_Build_an_Android_Project_with_Eclipse. Also read “The Cocos2d-x project structure” below.

If you just want to start development of a new game, see this link: http://cocos2d-x.org/wiki/How_to_Start_A_New_Cocos2D-X_Game. The command-line commands at the end of this article may help. Also read “The Cocos2d-x project structure” below.

NOTE:
When using the Cpp-test project in Eclipse, import the project at “[your Cocos2d-x root]cocos\platform\android\java” instead of “[your Cocos2d-x root]cocos/2d/platform/android/java”

NOTE:
In Eclipse, one needs to import the Cocos2d-x library into the project. It is called libcocos2dx and can be found in the project folder. Import it into an Eclipse project to make it use cocos2dx. Go to 10:00 in the following video to see how to do this: http://www.youtube.com/watch?v=B9ObAzm6rnQ&list=PLRtjMdoYXLf4od_bOKN3WjAPr7snPXzoe&index=3.

Fixing the slow Android emulator

Use the fast Android emulator instead! (also do read the note below) See installation guides here: https://software.intel.com/en-us/android/articles/intel-hardware-accelerated-execution-manager and thread here: http://stackoverflow.com/questions/1554099/why-is-the-android-emulator-so-slow. Keep in mind that using an x86 emulator may cause certain libraries to fail if they only come with an ARM version. There are other options, though. See the following thread for more: https://www.infinum.co/the-capsized-eight/articles/is-your-android-emulator-just-too-slow. The heading “Configuring Virtual Machine Acceleration” in the following link may also provide some guidance: http://developer.android.com/tools/devices/emulator.html.

NOTE:
Using the x86 emulator, you will get an “UnsatisfiedLinkError” when trying to run your app if you use the standard project setup, see http://methodcoder.blogspot.se/2014/03/cocos2d-x-android-unsatisfiedlinkerror.html including the comment. This is because the project binaries for Android are compiled for the ARM architecture by default. To get around this, add “APP_ABI := armeabi armeabi-v7a x86” to Application.mk in your Cocos project, see http://www.cocos2d-x.org/wiki/Build_HelloWorld_on_android_x86_platform and also http://stackoverflow.com/questions/10098049/android-ndk-build-ignoring-app-abi-x86. This will generate both ARM and x86 binaries, Eclipse will automatically choose the right one to run.

The Cocos2d-x project structure

The main files to change are located under the “Classes” folder of your project directory. In a newly created project, the HelloWorldScene files typically contain the most code. The files for your app activity is located under the folder “src”, and the images used in the app are located in the “Resources” folder which is above the folder of the projects. There is also an “assets” folder which will automatically copy images from the “Resources” folder, see http://rstechjournal.blogspot.se/2014/08/cocos2d-x-android-resources-vs-assets.html.

For more information about the programming concepts of Cocos2dx, such as Director or Scene, see this blog post: http://sunny1304.svbtle.com/cocos2d-x-tutorials-part-2-adding-sprite. You can find more detailed information about these concepts at the official Cocos2dx wiki under “Modules/Scene Graph”. Note in particular that the “Layer” structure should no longer be used in Cocos2dx version 3: http://cocos2d-x.org/wiki/Layer.

The files that help compile your project are called build_native.py, Android.mk and Application.mk. The file build_native.py is the build script to run when you want to compile the project. Application.mk and Android.mk are makefiles which are used in build_native.py. You should go to the folder “proj.android\jni” in your project folder to find the correct Application.mk and Android.mk for the Android project.

Especially Android.mk is important if you want to include or activate new functionality in your Cocos2dx project, for example new source files, the network/Http support in Cocos2dx or any functions from the extensions library. If no change in Android.mk is done, no class in those libraries will be usable and you will most likely get an “undefined reference” error when trying to use such a class. To avoid this, do the following:

If you want to include a new source file:
In Android.mk:
Add the .cpp file to LOCAL_SRC_FILES

If you want to include network support and extensions:

In Android.mk:
Make sure the following lines are uncommented:

LOCAL_WHOLE_STATIC_LIBRARIES += cocos_network_static
LOCAL_WHOLE_STATIC_LIBRARIES += cocos_extension_static

$(call import-module,network)
$(call import-module,extensions)

In HelloWorldScene.h (adjust the paths to match the ones in your Cocos2dx project):

#include “D:\Testgame\cocos2d\cocos\network\HttpClient.h”
#include “D:\Testgame\cocos2d\extensions\cocos-ext.h”

Also use the namespace cocos2d::network or cocos2d::extension depending on what function you are using. Please keep note 3 in the beginning of this article in mind.

Troubleshooting

If you get “Unable to locate tools.jar”, you probably use the JRE instead of the JDK. Make sure to set the JAVA_HOME environment variable to point to the JDK root (not the JRE root). See: http://stackoverflow.com/questions/2618281/ant-error-when-trying-to-build-file-cant-find-tools-jar

If you forget to include a necessary file in the Android.mk file (see “The Cocos2d-x project structure” above) an “expected namespace name” error can be had at the place where you try to use the namespace (e.g. a “using namespace cocos2d::extension;” statement). This is because without the right include, your namespace will not be recognized as a namespace.

If your project complains on something like “Multiple dex files define Lorg/cocos2dx/lib/Cocos2dxAccelerometer;”, see: http://stackoverflow.com/questions/7870265/unable-to-execute-dex-multiple-dex-files-define-lcom-myapp-rarray or http://discuss.cocos2d-x.org/t/conversion-to-dalvik-format-failed-unable-to-execute-dex-multiple-dex-files-define-lorg-cocos2dx-lib-cocos2dxaccelerometer/6652/3
Basically, in Eclipse, just go to the Properties->Java build path->Source of your project and remove libcocos2dx. Then try to run the project again.

In Eclipse, it may sometimes be necessary to right click the project, select “Properties”, then “Builders” and remove builders with errors. See https://www.youtube.com/watch?v=B9ObAzm6rnQ&index=3&list=PLRtjMdoYXLf4od_bOKN3WjAPr7snPXzoe for more info.

If you get a “No space left on device” error when using “adb install APPNAME.apk” it probably means that the device does not have enough internal memory for the app. Clean the memory or use the command “adb install -s APPNAME.apk” to install it on the SD card of your phone.

If your app cannot connect to the internet, make sure you have set the correct permissions in AndroidManifest.xml. The following apply (from https://developers.nextpeer.com/docs/view/cocos2dx-v3):

<!-- Required. Used to access the Internet to make network requests. -->
<uses-permission android:name="android.permission.INTERNET"/>

<!-- Optional - Used to check if an Internet connection is available prior to making network requests -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

Additional information

USING_NS_CC is a shortcut for “using namespace cocos2d”.

“#pragma once” can be used instead of include guards.

Cocos2dx is widely used in China and http://en.chukong-inc.com/ seems to be maintaining and sponsoring it. However, according to Wikipedia, the Cocos2d project (without the final x) was first created by Ricardo Quesada from Argentina.

Sometimes, the Chinese Cocos2dx wiki has better information than the English one, most likely because a Chinese company is one of the main maintainers of the framework. Try to use Google Translate or similar technology to gain access to this information if you do not understand Chinese.

Good basic tutorials:
– https://www.youtube.com/watch?v=B9ObAzm6rnQ&index=3&list=PLRtjMdoYXLf4od_bOKN3WjAPr7snPXzoe

– http://sunny1304.svbtle.com/

Emulator keyboard commands: http://developer.android.com/tools/help/emulator.html

Android screencast tool: https://code.google.com/p/android-screen-monitor/

Android video capture tools: If you just want to record a video on the Android device itself there are a few options. If your device has Android 4.4 or higher see “Recording a device screen” here: http://developer.android.com/tools/help/adb.html#screenrecord. Also see the tips here and here. Especially the information about turning on touch display is handy. For earlier versions of Android, or if you run into problems, the following link may be of help: http://www.phonearena.com/news/Heres-how-to-record-screen-video-on-Android_id28727

JSON (and XML) with Cocos2dx (from the Chinese Cocos2dx wiki): https://translate.googleusercontent.com/translate_c?depth=1&hl=sv&rurl=translate.google.se&sl=auto&tl=en&u=http://cn.cocos2d-x.org/article/index%3Ftype%3Dcocos2d-x%26url%3D/doc/cocos-docs-master/manual/framework/native/v3/json-parse/zh.md&usg=ALkJrhhnhUEQxHzieb_4paMExR3xShQJIA

RapidJSON tutorial (RapidJSON is the standard JSON parser included in Cocos2dx version 3): http://miloyip.github.io/rapidjson/md_doc_tutorial.html#ValueDocument

RapidJSON example:

#include "../cocos2d/external/json/rapidjson.h"
#include "../cocos2d/external/json/document.h"

std::string str = "{\"hello\": \"world\", \"t\": true , \"f\": false, \"n\": null, \"i\": 123, \"pi\": 3.1416, \"a\": [1, 2, 3, 4]}";
CCLOG("%s\n", str.c_str()); // Transform string to c_str
rapidjson::Document rapidjson_document;
rapidjson_document.Parse<0>(str.c_str()); // The JSON is now parsed into document as a DOM tree (assumes JSON stored in a C string)

Command-line commands:

These commands assume that you have set the “SDK_ROOT/tools” and “SDK_ROOT/plattform-tools” according to step 1 under “Installation instructions” above and subsequently started a new terminal window and/or restarted the computer.

Use “android avd” to start emulator.

Use “adb devices” to list all devices.

Use “adb -d SOME_COMMAND” to target (a lone) USB connected device and “adb -e SOME_COMMAND” to target (a lone) available emulator. See: http://www.shockoe.com/blog/adb-with-multiple-devices/ and http://www.alittlemadness.com/2010/06/15/android-ant-builds-targeting-a-specific-device/

Use the command “monitor” to start the Android Device Monitor. In this tool you can for example see logcat debugging messages, manage your Android emulators and send geolocation data to the Android emulator.

Use the -r parameter/flag with “adb install” to reinstall the app.

Use the -s parameter/flag with “adb install” to install the app on the SD card rather than the internal memory.

See http://developer.android.com/tools/help/adb.html for more commands.