Fr

ee

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.

What you will learn from this book

Set up your work environment
Learn how to create graphic elements and
animate them
Use the built-in physics engine to make your
games more realistic

Building Android Games with Cocos2d-x

Building Android
Games with Cocos2d-x

pl

Manage user interaction using the touch and

accelerometer capabilities
Boost your game's visual appeal by learning to
add text and using true type and bitmap fonts

C o m m u n i t y

Enhance your game by adding sound effects

and background music
Discover how to add rich explosion effects
using particle systems

If you have a basic understanding of the C++ programming

language and want to create videogames for the Android
platform, then this technology and book is ideal for you.

Add native Java code to your Android game

$ 24.99 US
16.99 UK

Raydelto Hernandez

Who this book is written for

E x p e r i e n c e

community experience distilled

Learn to create engaging and spectacular games for Android

using Cocos2d-x

Prices do not include

local sales tax or VAT
where applicable

Visit www.PacktPub.com for books, eBooks,

code, downloads, and PacktLib.

D i s t i l l e d

Building Android Games

with Cocos2d-x
Foreword by Carlos Pian, CTO, Vitrum Games

P U B L I S H I N G

Sa
m

Raydelto Hernandez

In this package, you will find:

The author biography

A preview chapter from the book, Chapter 1 'Setting Up Your
Development Environment'
A synopsis of the books content
More information on Building Android Games with Cocos2d-x

About the Author

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.

Building Android Games with

Cocos2d-x
Cocos2d-x is the most used open source game framework. It has official support from
Microsoft for their mobile and desktop platform, and its small core runs faster than other
frameworks, allowing it to run on low-end Android devices with outstanding
performance. It is currently maintained by an active open source development community
led by the author of the original Cocos2d for iPhone and Chukong Technologies.
This introductory book will guide you through the steps for creating a simple twodimensional game for Android from scratch. During this journey, you will learn the
fundamentals of the Cocos2d-x C++ multiplatform game framework and how to handle
sprites, add physics to your games, play sounds, display text, generate realistic explosions
using particle systems, and add native Android functionalities using Java Native
Interface (JNI).

What This Book Covers

Chapter 1, Setting Up Your Development Environment, guides you step by step for
configuring Cocos2d-x and all its prerequisites.
Chapter 2, Graphics, covers handling backgrounds, sprites, animating them, and boosting
their performance using sprite sheets.
Chapter 3, Understanding Game Physics, demonstrates the basics of the new Cocos2d-x
physics engine based on Chipmunk, which was introduced in Cocos2d-x version 3.0. We
will create physics-based bodies, add gravity to them, and detect collisions.
Chapter 4, User Input, is where we add interaction to our game, allowing it to interact
with the user with the help of touch listeners and the accelerometer.
Chapter 5, Handling Text and Fonts, proves that handling text is crucial for game
development. Irrespective of the complexity of your game, the odds are that you will
display information, sometimes with foreign character sets. This chapter shows you how
to use simple true-type fonts and more stylized bitmap fonts to make your game look
more professional.
Chapter 6, Audio, shows that part of the emotion of playing a game comes from the
music and sound effects. Within this chapter, you learn how to add background music
and sound effects to your game using the CocosDenshion audio engine, which has been
present since the original Cocos2d iPhone game engine. This chapter also covers how to
play media using the new audio engine and highlights the major differences
between them.

Chapter 7, Creating Particle Systems, illustrates the creation of realistic explosions, fire,
snow, rain using the built-in particle systems engine. This chapter shows you how to
create your own particle system when you require a customized effect, using the most
popular tools.
Chapter 8, Adding Native Java Code, helps you when you need to add native code for
creating and invoking Android-specific behavior from within your Cocos2d-x game
activity. We do this using the Java Native Interface (JNI) mechanism, available on the
Android platform.

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

[1]

Setting Up Your Development Environment

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 http://www.oracle.com/

technetwork/java/javase/downloads/java-archive-downloadsjavase6-419409.html 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.

[2]

Chapter 1

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: http://developer.android.com/
sdk. 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:

[3]

Setting Up Your Development Environment

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
http://www.eclipse.org/downloads. 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.

[4]

Chapter 1

Setting up the Eclipse ADT plugin

Open Eclipse and navigate to Help | Install new Software and add the Eclipse ADT
download location, which is https://dl-ssl.google.com/android/eclipse/,
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:
https://developer.android.com/tools/sdk/ndk
[5]

Setting Up Your Development Environment

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: https://www.apache.org/dist/ant/
binaries/

At the time of writing this book, version 1.9.4 was the latest. This tool is a crossplatform 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:
https://www.python.org/ftp/python/2.7.8/python-2.7.8.msi.
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.

[6]

Chapter 1

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 http://www.cocos2d-x.org/
download. 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 setup.py. 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.

[7]

Setting Up Your Development Environment

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:

[8]

Chapter 1

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.

[9]

Setting Up Your Development Environment

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.
[ 10 ]

Chapter 1

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 Android.mk 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) {

[ 11 ]

Setting Up Your Development Environment

glview = GLViewImpl::create("My Game");
director->setOpenGLView(glview);
}
// turn on display FPS
director->setDisplayStats(false);
// 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
director->runWithScene(scene);
return true;
}

Downloading the example code

You can download the example code fies for all Packt books you
havepurchased from your account at http://www.packtpub.
com. If youpurchased this book elsewhere, you can visit http://
www.packtpub.com/support and register to have the fies
e-mailed directly to you.

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

[ 12 ]

Chapter 1

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

[ 13 ]

Get more information Building Android Games

Where to buy this book

You can buy Building Android Games with Cocos2d-x from the
Packt Publishing website.
Alternatively, you can buy the book from Amazon, BN.com, Computer Manuals and most internet
book retailers.
Click here for ordering and shipping details.

www.PacktPub.com

Stay Connected: