In this article written by Akihiro Matsuura, author of the book Cocos2d-x Cookbook, we're going to install Cocos2d-x and set up the development environment. The following topics will be covered in this article:

Installing Cocos2d-x
Using Cocos command
Building the project by Xcode
Building the project by Eclipse

Cocos2d-x is written in C++, so it can build on any platform. Cocos2d-x is open source written in C++, so we can feel free to read the game framework. Cocos2d-x is not a black box, and this proves to be a big advantage for us when we use it. Cocos2d-x version 3, which supports C++11, was only recently released. It also supports 3D and has an improved rendering performance.

(For more resources related to this topic, see here.)

Installing Cocos2d-x

Getting ready

To follow this recipe, you need to download the zip file from the official site of Cocos2d-x (http://www.cocos2d-x.org/download).

In this article we've used version 3.4 which was the latest stable version that was available.

How to do it...

Unzip your file to any folder. This time, we will install the user's home directory. For example, if the user name is syuhari, then the install path is /Users/syuhari/cocos2d-x-3.4. We call it COCOS_ROOT.
The following steps will guide you through the process of setting up Cocos2d-x:
- Open the terminal
- Change the directory in terminal to COCOS_ROOT, using the following comand:
```
$ cd ~/cocos2d-x-v3.4
```
- Run setup.py, using the following command:
```
$ ./setup.py
```
- The terminal will ask you for NDK_ROOT. Enter into NDK_ROOT path.
- The terminal will will then ask you for ANDROID_SDK_ROOT. Enter the ANDROID_SDK_ROOT path.
- Finally, the terminal will ask you for ANT_ROOT. Enter the ANT_ROOT path.
- After the execution of the setup.py command, you need to execute the following command to add the system variables:
```
$ source ~/.bash_profile
```
Open the .bash_profile file, and you will find that setup.py shows how to set each path in your system. You can view the .bash_profile file using the cat command:
```
$ cat ~/.bash_profile
```
We now verify whether Cocos2d-x can be installed:
Open the terminal and run the cocos command without parameters.
```
$ cocos
```
If you can see a window like the following screenshot, you have successfully completed the Cocos2d-x install process.

How it works...

Let's take a look at what we did throughout the above recipe. You can install Cocos2d-x by just unzipping it. You know setup.py is only setting up the cocos command and the path for Android build in the environment. Installing Cocos2d-x is very easy and simple. If you want to install a different version of Cocos2d-x, you can do that too. To do so, you need to follow the same steps that are given in this recipe, but which will be for a different version.

There's more...

Setting up the Android environment is a bit tough. If you started to develop at Cocos2d-x soon, you can turn after the settings part of Android. And you would do it when you run on Android. In this case, you don't have to install Android SDK, NDK, and Apache. Also, when you run setup.py, you only press Enter without entering a path for each question.

Using the cocos command

The next step is using the cocos command. It is a cross-platform tool with which you can create a new project, build it, run it, and deploy it. The cocos command works for all Cocos2d-x supported platforms. And you don't need to use an IDE if you don't want to. In this recipe, we take a look at this command and explain how to use it.

How to do it...

You can use the cocos command help by executing it with the --help parameter, as follows:
```
$ cocos --help
```
We then move on to generating our new project:
Firstly, we create a new Cocos2d-x project with the cocos new command, as shown here:
```
$ cocos new MyGame -p com.example.mygame -l cpp -d ~/Documents/
```
The result of this command is shown the following screenshot:

Behind the new parameter is the project name. The other parameters that are mentioned denote the following:
- MyGame is the name of your project.
- -p is the package name for Android. This is the application id in Google Play store. So, you should use the reverse domain name to the unique name.
- -l is the programming language used for the project. You should use "cpp" because we will use C++.
- -d is the location in which to generate the new project. This time, we generate it in the user's documents directory.
You can look up these variables using the following command:
```
$ cocos new —help
```
Congratulations, you can generate your new project. The next step is to build and run using the cocos command.
Compiling the project
If you want to build and run for iOS, you need to execute the following command:
```
$ cocos run -s ~/Documents/MyGame -p ios
```
The parameters that are mentioned are explained as follows:
- -s is the directory of the project. This could be an absolute path or a relative path.
- -p denotes which platform to run on.If you want to run on Android you use -p android. The available options are IOS, android, win32, mac, and linux.
- You can run cocos run –help for more detailed information.
The result of this command is shown in the following screenshot:
You can now build and run iOS applications of cocos2d-x. However, you have to wait for a long time if this is your first time building an iOS application. That's why it takes a long time to build cocos2d-x library, depending on if it was clean build or first build.

How it works...

The cocos command can create a new project and build it. You should use the cocos command if you want to create a new project. Of course, you can build by using Xcode or Eclipse. You can easier of there when you develop and debug.

There's more...

The cocos run command has other parameters. They are the following:

--portrait will set the project as a portrait. This command has no argument.
--ios-bundleid will set the bundle ID for the iOS project. However, it is not difficult to set it later.

The cocos command also includes some other commands, which are as follows:

The compile command: This command is used to build a project. The following patterns are useful parameters. You can see all parameters and options if you execute cocos compile [–h] command.
```
cocos compile [-h] [-s SRC_DIR] [-q] [-p PLATFORM] [-m MODE] 
```
The deploy command: This command only takes effect when the target platform is android. It will re-install the specified project to the android device or simulator.
```
cocos deploy [-h] [-s SRC_DIR] [-q] [-p PLATFORM] [-m MODE]
```
The run command continues to compile and deploy commands.

Building the project by Xcode

Getting ready

Before building the project by Xcode, you require Xcode with an iOS developer account to test it on a physical device. However, you can also test it on an iOS simulator. If you did not install Xcode, you can get it from Mac App Store. Once you have installed it, get it activated.

How to do it...

Open your project from Xcode.
You can open your project by double-clicking on the file placed at: ~/Documents/MyGame/proj.ios_mac/MyGame.xcodeproj.
Build and Run by Xcode
You should select an iOS simulator or real device on which you want to run your project.

How it works...

If this is your first time building, it will take a long time. But continue to build with confidence as it's the first time. You can develop your game faster if you develop and debug it using Xcode rather than Eclipse.

Building the project by Eclipse

Getting ready

You must finish the first recipe before you begin this step. If you have not finished it yet, you will need to install Eclipse.

How to do it...

Setting up NDK_ROOT:
- Open the preference of Eclipse
- Open C++ | Build | Environment
Click on Add and set the new variable, name is NDK_ROOT, value is NDK_ROOT path.
Importing your project into Eclipse:
- Open the file and click on Import
- Go to Android | Existing Android Code into Workspace
- Click on Next
Import the project to Eclipse at ~/Documents/MyGame/proj.android.
Importing Cocos2d-x library into Eclipse
- Perform the same steps from Step 3 to Step 4.
- Import the project cocos2d lib at ~/Documents/MyGame/cocos2d/cocos/platform/android/java, using the folowing command:
importing cocos2d lib
Build and Run
- Click on Run icon
- The first time, Eclipse asks you to select a way to run your application. You select Android Application and click on OK, as shown in the following screenshot:
- If you connected the Android device on your Mac, you can run your game on your real device or an emulator. The following screenshot shows that it is running it on Nexus5.
If you added cpp files into your project, you have to modify the Android.mk file at ~/Documenst/MyGame/proj.android/jni/Android.mk. This file is needed to build NDK. This fix is required to add files.

The original Android.mk would look as follows:

LOCAL_SRC_FILES := hellocpp/main.cpp 

                   ../../Classes/AppDelegate.cpp 

                   ../../Classes/HelloWorldScene.cpp

If you added the TitleScene.cpp file, you have to modify it as shown in the following code:

LOCAL_SRC_FILES := hellocpp/main.cpp 
                   ../../Classes/AppDelegate.cpp 
                   ../../Classes/HelloWorldScene.cpp 
                   ../../Classes/TitleScene.cpp

The preceding example shows an instance of when you add the TitleScene.cpp file. However, if you are also adding other files, you need to add all the added files.

How it works...

You get lots of errors when importing your project into Eclipse, but don't panic. After importing cocos2d-x library, errors soon disappear. This allows us to set the path of NDK, Eclipse could compile C++. After you modified C++ codes, run your project in Eclipse. Eclipse automatically compiles C++ codes, Java codes, and then runs.

It is a tedious task to fix Android.mk again to add the C++ files. The following code is original Android.mk:

LOCAL_SRC_FILES := hellocpp/main.cpp 
                   ../../Classes/AppDelegate.cpp 
                   ../../Classes/HelloWorldScene.cpp

LOCAL_C_INCLUDES := $(LOCAL_PATH)/../../Classes

The following code is customized Android.mk that adds C++ files automatically.

CPP_FILES := $(shell find $(LOCAL_PATH)/../../Classes -name *.cpp)
LOCAL_SRC_FILES := hellocpp/main.cpp
LOCAL_SRC_FILES += $(CPP_FILES:$(LOCAL_PATH)/%=%)

LOCAL_C_INCLUDES := $(shell find $(LOCAL_PATH)/../../Classes -type d)

The first line of the code gets C++ files to the Classes directory into CPP_FILES variable. The second and third lines add C++ files into LOCAL_C_INCLUDES variable. By doing so, C++ files will be automatically compiled in NDK. If you need to compile a file other than the extension .cpp file, you will need to add it manually.

There's more...

If you want to manually build C++ in NDK, you can use the following command:

$ ./build_native.py

This script is located at the ~/Documenst/MyGame/proj.android . It uses ANDROID_SDK_ROOT and NDK_ROOT in it. If you want to see its options, run ./build_native.py –help.

Summary

Cocos2d-x is an open source, cross-platform game engine, which is free and mature. It can publish games for mobile devices and desktops, including iPhone, iPad, Android, Kindle, Windows, and Mac. The book Cocos2d-x Cookbook focuses on using version 3.4, which is the latest version of Cocos2d-x that was available at the time of writing. We focus on iOS and Android development, and we'll be using Mac because we need it to develop iOS applications.