Building Android Games with Cocos2d-x

By Raydelto Hernandez
    Advance your knowledge in tech with a Packt subscription

  • Instant online access to over 7,500+ books and videos
  • Constantly updated with 100+ new titles each month
  • Breadth and depth in over 1,000+ technologies
  1. Setting Up Your Development Environment

About this book

Cocos2d-x is a multi-platform C++ gaming framework in active development maintained by Chukong technologies. It wraps all the essential elements needed for creating a game, making the task of game building very developer-friendly.

Starting with a vital primer to get you up and running with your development environment, you will quickly dive in to exploring the latest version of this framework. You will understand major framework improvements to render objects at lightning speed, extend and maintain code easily, and improve the label API to add great functionality such as glow, shadows, and outlines to labels.

Through the creation of a real game, you will explore the core components of development including Physics, enabling you to create realistic sprite movements, and particle systems to dynamically simulate explosions, fire, rain, and smoke, as well as exploring the sound engine to make your game more robust. Finish by integrating Cocos2d-x C++ code with native Android code to launch games with the classic Java Android application.

Publication date:
March 2015


Chapter 1. Setting Up Your Development Environment

In this chapter, we will explain how to download and set up all the required tools to get you started with setting up an environment for building games for the Android platform. Although there are huge similarities between the Mac OS and the Windows development environment, we will cover all the details regarding the installation in both of these operating systems.

The following topics will be covered in this chapter:

  • Cocos2d-x overview

  • Setting up Java

  • Setting up the Android SDK

  • Setting up the Android Native Development Kit (NDK)

  • Setting up Apache Ant

  • Setting up Python

  • Setting up Cocos2d-x

  • Setting up the Eclipse IDE

  • Template code walk-through


Cocos2d-x overview

Cocos2d-x is a C++ cross-platform port of the popular iOS gaming framework Cocos2d. It was first released in November 2010, and bought in 2011 by Chukong Technologies, a Beijing-based mobile gaming company. Nevertheless, it is still maintained by an active community of more than 400,000 developers worldwide, including Ricardo Quesada, the creator of the original Cocos2d iPhone engine.

This framework encapsulates all the game details, such as sound, music, physics, user inputs, sprites, scenes, and transitions, so the developer will only have to focus on the game logic rather than re-inventing the wheel.


Setting up Java

The Android platform technology stack is based on the Java technology; that is why the first item to be downloaded will be the Java Development Kit (JDK). Although Java JDK 8 is the latest version at the time of writing this book, it is not officially supported by all Android versions, so we will download JDK 6, all the template Java codes generated by Cocos2d-x can be successfully compiled with this version.


Java Runtime Environment (JRE) is not enough for building the Android applications, since it only contains the files required for running the Java applications, but it does not contain the tools required for building the Java applications.

You can download the JDK 6 from Oracle at regardless of your development environment.

If Windows is your current environment, then after installing JDK you are required to add the path of the binaries folder to the PATH environment variable. This path will look like this: C:\Program Files\Java\jdk1.6.0_45\bin.

Open a new system console and type javac –version, if Java compiler's version number is displayed, then you have successfully installed JDK in your system.


JDK 7 is required for building the applications for Android 5.0 and higher. You should download this version if you are targeting the latest Android versions. But, if you want your game to be compatible with the Android versions that are older than 4.4, then you should pick JDK 6.


Setting up the Android SDK

The Android SDK contains all the required command line tools for building an Android application. It has versions for Windows, Mac, and GNU/Linux operating systems.

Android Studio is now the only officially supported IDE; nevertheless, Cocos2d-x 3.4 provides only out-of-the-box support for Eclipse, which was the former official IDE for Android development. It is no longer available for downloading, since it is not in active development any more, but you may download Eclipse manually and install the Android Development Tools (ADT) by following the steps below.

Downloading the Android SDK

You can download Android SDK from the link: At the bottom of the page, under Other Download Options, you will find the option for downloading the SDK tools. Choose the version that matches your operating system.

At the time of writing this book, the latest version of SDK was 24.0.2.

Run the Android SDK Installer and install the Android SDK on your computer.

When the Android SDK finishes installing, it is not yet ready to build the Android apps. So, at the final screen of the installation wizard, mark the checkbox for Start SDK Manager so you can download the required components for building your games, as shown in the following screenshot:

Once the Android SDK Manager starts, select Android SDK Platform-tools and Android SDK Build-tools from the Tools folders. Then select SDK Platform from your desired API level, as shown in the following screenshot:

Downloading Eclipse

Download the latest version of the Eclipse IDE for Java Developers from It will suggest the download versions compatible with your current operating system, select the version that better suits your operating system platform which will either be 32-bit or 64-bit.

At the time of writing this book, Eclipse Luna (4.4.1) was the latest version.

Setting up the Eclipse ADT plugin

Open Eclipse and navigate to Help | Install new Software and add the Eclipse ADT download location, which is, as shown in the following screenshot:

Click on OK, then select the Developer Tools checkbox, and click on Next in order to finish the ADT installation wizard.


Setting up the Android Native Development Kit

We have already downloaded the Android SDK that allows you to create Android applications using the Java Technology; nevertheless, the Cocos2d-x framework is written in C++, so you will need the Android Native Development Kit (NDK) in order to build the C++ code for the Android platform.


Android's official documentation clearly states that you should use this native kit for specific circumstances, but you should not use it just because you are familiar with the C++ language, or because you want your application to perform faster. The manufacturer makes this suggestion because the Android core API is only available for Java.

Download the latest NDK revision. At the time this book was written, it was 10d. This version of NDK will allow you to build for all the Android platforms, including the latest.

You can download the latest version of the Android NDK for all the platforms from the following link:

After downloading it, run the executable file. It will decompress the Android NDK directory on the current path; you need to be aware of this path since you will need it later.


Setting up Apache Ant

Apache Ant is a build management tool widely used for automating the Java projects build process. It has been introduced in Cocos2d-x 3.0 for building the framework for the Android platform. It has made the Android build process simpler and enhanced the cross-platform build. Back in Cocos2d-x 2.x, building the Android apps within the Windows operating system required simulating the UNIX environment by using Cygwin. This required minor hacks for successfully building the code, many of them still remain undocumented on the official Cocos2d-x site.

This tool can be downloaded from the link:

At the time of writing this book, version 1.9.4 was the latest. This tool is a cross-platform tool so a single download will work on any operating system that provides support for the Java technology.

In order to install this tool, just unzip the file. Remember the path since you will need it during the Cocos2d-x setup process.


Setting up Python

All the Cocos2d-x configuration files are written in Python. If you are using Mac OS or any Linux distribution, it will already be installed on your OS. So, you can skip this section.

If you are using Windows, you need to download Python 2 from the following link:

Take in to consideration that Python, as Cocos2d-x, keeps simultaneous support for versions 2 and 3. Cocos2d-x only supports Python 2. At the time of writing this book the latest version of the 2 branch was 2.7.8.

After the installer finishes with the setup, you should manually add the Python installation path to the PATH environment variable. The default installation path is C:\Python27.

Open a new system console and type python, if the Python console is shown, as seen in the following screenshot, then it means that Python has been installed correctly:


For setting an environment variable on Windows, click on the Start button and type: edit the system environment variables, click on it and hit the Environment Variables button, and then the environment variables configuration dialog will be displayed.


Setting up Cocos2d-x

Now that you have all the Cocos2d-x pre-requisites for building your first game for the Android platform, you are going to download the Cocos2d-x 3.4 framework and set it up with the help of the following steps:

  1. You can download the source code from Be aware that this page also has the link for downloading the Cocos2d-x branch 2, which is not covered in this book, and the manufacturer has officially announced that the new features will only be available in branch 3.

  2. After downloading the compressed Cocos2d-x source code, uncompress it to your desired location.

  3. In order to configure Cocos2d-x, open your system terminal and point to the path where you have uncompressed it, and type It will require you to specify ANDROID_NDK_PATH, here you will specify the root directory of the NDK that you have previously uncompressed in the previous sections. Secondly, it will require you to specify ANDROID_SDK_ROOT, here you will specify the directory path from where you have chosen to install the Android SDK during the installation process. Then, it will require you to set ANT_ROOT, where you will specify the root directory of your ant installation. Finally, close the terminal, and open a new one so that the changes can take effect.

Creating your first project

Now, Cocos2d-x is set up, and it is ready for creating your first project. You can do so by typing the following command:

 cocos new MyGame -p com.your_company.mygame -l cpp -d NEW_PROJECTS_DIR

This script has created an Android template code for your game that will run in all the Android devices containing the Android API 9 or higher, that is Android 2.3 (Gingerbread) and later.

Take in to consideration that the package name should contain exactly two dots, as the example shows, if it has less or more, then the project creation script will not work. The –l cpp parameter means that the new project is going to use C++ as the programming language, which is the only one that is covered in this book.

Cocos2d-x 3.x, as opposed to branch 2.x, allows you to create your project outside of the framework directory structure. Therefore, you can create your project at any location, and not just inside the projects directory, as it was in the previous versions.

It will take a while, since it will copy all the framework files to your new project's path. After it finishes, plug your Android device to your computer, then you can easily run the template HelloWorld code by typing the following command within your new project's path:

cocos run -p android

Alternatively, you could run the following command regardless of your current path on the terminal:

cocos run -p android /path/to/project


For building and running Cocos2d-x 3.4 for Windows, you will need Microsoft Visual Studio 2012 or 2013.

Now, you should be able to see the Cocos2d-x logo and a text that says Hello World, as we can see in the following image:

Setting up the Eclipse IDE

Cocos2d-x branch 3 has improved the Android building process significantly.

Back in branch 2, it was necessary to manually configure many environment variables within IDE, import many core projects, and handle dependencies. Even after completing all the steps, the Cygwin Windows UNIX port integration with Eclipse was never polished to work flawlessly, so minor hacks were required.

Building Cocos2d-x 3.4 within Eclipse is as simple as importing the project and clicking on the Run button. In order to achieve this, within the ADT, navigate to File | Import | General | Existing Projects into Workspace, select the path, where Cocos2d-x has created the new project from the previous sections. Then click on Finish.


Cocos2d-x Android template project is created using the API Level 10 as target platform. If you don't have this version installed on your system, you should change it by right-clicking on the project from the package explorer, click on Properties, and select your preferred installed Android API version from the Project Build Target box.

Now, right-click on the project name in the package explorer, click on run as, and finally, click on Android Application. The following pop up will be displayed, and it will require you to specify the Android device on which you want to launch the Cocos2d-x game:

After picking your Android device, you will see the HelloWorld game scene as it was shown when we ran the Run command in the previous section.


Template code walk-through

In this section, we will explain the main parts of the Cocos2d-x template code generated in the previous sections by the project creation script.

Java classes

We now have one Java class in our project named AppActivity that has no members and extends the Cocos2dxActivity class from the core library. We can also see that 22 Java classes from the core library have been referenced in the project. This code is aimed to make our C++ code work, and we don't have to modify it at all.

Android application configuration

The generated AndroidManifest.xml, which is the android configuration file, requires the permission android.permission.INTERNET, which allows your Android application to use the Internet connection on your device; nevertheless, this is not needed by our simple game code since there is no Internet interaction. So, you may delete this line from the AndroidManifest.xml file if you wish. Your game will be shown in landscape by default, but if you wish to create a game that runs in portrait mode, then you should change the android:screenOrientation value from landscape to portrait.

In order to change the Android application name, you may modify the app_name value located on the strings.xml file; it will affect the launcher icon's text and the application identifier within the Android OS.

When you are creating your own games, you will have to create your own classes, and those will often be more than the two classes that were created by the script. Every time you create a new class, you need to add its name to the LOCAL_SRC_FILES property of the make file located inside the jni folder of your new project directory structure. So, when your cpp code is built by the C++ build tools, it knows which files it should compile.

C++ classes

Two C++ classes have been created: AppDelegate and HelloWorldScene. The first one is in charge of launching the Cocos2d-x framework and passing the control to the developer. The framework loading process happens within this class. If the Cocos2d-x core framework is successfully launched on the target device, it will run the applicationDidFinishLaunching method, which is the first game-specific function to be run.

The code is very straightforward and it is documented such that you will be able to grasp its logic easily. Our first minor change to the code will be to hide the debug information that shows by default on this sample game. You could simply guess that in order to achieve this you should only send false as a parameter for the setDisplayStats method call in the director singleton instance, as we can see in the following code listing:

bool AppDelegate::applicationDidFinishLaunching() {
    // initialize director
    auto director = Director::getInstance();
    auto glview = director->getOpenGLView();
    if(!glview) {
        glview = GLViewImpl::create("My Game");
    // turn on display FPS
    // set FPS. the default value is 1.0/60 if you don't call this
    director->setAnimationInterval(1.0 / 60);
    // create a scene. it's an autorelease object
    auto scene = HelloWorld::createScene();
    // run
    return true;


Downloading the example code

You can download the example code files for all Packt books you have purchased from your account at If you purchased this book elsewhere, you can visit and register to have the files e-mailed directly to you.


As we will cover in the chapters later in this book, Cocos2d-x handles the scene concept just like movies; movies are composed by scenes, so are the Cocos2d-x games. We can visualize the different screens, such as loading, main menu, world selection, gameplay levels, ending credits, and so on, as the different scenes. Each scene has a class that defines its behavior. The template code has only one scene named HelloWorld scene that is initialized and launched from within the AppDelegate class. The scene flow is managed by the game director as we have seen in the previous code. The Director class has all the basic features to drive the game, just like a director does during a movie. There is a single shared instance of the director class that is used within the whole application scope.

HelloWorldScene contains the layer that represents all the visible areas that show up when we run our HelloWorld application, that is, the hello world label, the Cocos2d-x logo, and the menu showing the exit option.

Within the init method, we do the instantiation of the visual elements, and then we add it to the scene using the addChild method inherited from the Node core class.



In this chapter, we have introduced the Cocos2d-x 3.4 gaming framework, and explained how to download and install it. We have also explained all of its pre-requisites. We have configured our work environment, launched our first Android application into an actual device, and gone through a quick code overview of the main aspects of the template code generated by the script.

In the next chapter, we will cover how to create and manipulate all of our game graphics, such as the main character, enemies, obstacles, backgrounds, and so on.

About the Author

  • Raydelto Hernandez

    Raydelto Hernandez is a software engineer and university professor living in Santo Domingo, Dominican Republic. He has developed games for BlackBerry 10, Android, and iOS. He currently teaches topics related to game development at INTEC University.

    At the age of 22, he started teaching at Las Americas Institute of Technology, where he earned the Professor of the Year award many times. Then he the became director of the software development center. He has also taught at UNAPEC University, UNIBE University, and INTEC University, where he is currently a research professor.

    He is a BlackBerry Certified Builder, Zend Certified Engineer, Certified Java programmer, CompTIA A+ professional, and Microsoft Technology Associate.

    Raydelto has posted on YouTube dozens of video tutorials on different programming environments, which are also available on his website at Here, you can also find information about his open source projects.

    Raydelto has founded two technology companies, Soluciones GBH (in 2005) and AST Technology (in 2008), which develop software for all platforms.

    Browse publications by this author
Building Android Games with Cocos2d-x
Unlock this book and the full library for FREE
Start free trial