Create Multiplatform Games with Cocos2d-x* (Version 3.0 or Later)

In this tutorial you will learn how to create a simple game using the Cocos2d-x* framework, version 3.0 or later, in a Windows* development environment and how to compile it to run on Windows and Android*.

What Is Cocos2d-x?

Cocos2d-x is a cross-platform framework for games (and other graphical apps, like interactive books) based on the cocos2d for macOS*, but using C++, JavaScript*, or Lua instead of Objective-C*.

One of the advantages of this framework is to create games that can be deployed on different platforms (Android*, macOS, Win32, Windows* Phone, Mac*, Linux*, etc.), keeping the same code base with a few platform-specific adaptations for each one.

Cocos2d-x Console

The cocos2d-console was introduced in the 3.0 version. It is a command line tool that provides some functionality to manage Cocos2d-x or Cocos2d-JS projects like: creation, execution, building, debug, etc.

Create Your First Game

1. Download the latest version of the framework and unzip it in your development environment. In this tutorial the 3.3rc0 version was used, and the framework was unzipped to the desktop (C:\Users\intel-user\Desktop\cocos2d-x-3.3rc0).

Cocos2d-x directory structure
Figure 1. Cocos2d-x version 3.3 RC0 directory structure

2. To create a new project in Cocos2d-x, use setup.py (a Python* script) located in the framework folder to configure all the environment variables to build for Win32 and Android platforms. You will need to download, install and configure the items below before executing setup.py:

If you haven’t installed Python Runtime, download the 2.7.6 version.

setup.py location
Figure 2. setup.py location

3. Open the command prompt (cmd.exe) and execute the following commands:

Note: To run the Python command from the command prompt, was installed to the environment variable path.

  • Navigate to the script folder (framework folder)
    cd C:\Users\intel-user\Desktop\cocos2d-x-3.3rc0
  • Run the script setup.py:
    python setup.py (or setup.py only)
  • The script will request the installation path of Android SDK, Android NDK, and ANT.

Android NDK folder path:

Cocos2d console requesting N D K folder path
Figure 3. Cocos2d-console requesting NDK folder path

Android SDK folder path:

Cocos2d console requesting S D K folder path
Figure 4. Cocos2d-console requesting SDK folder path

Apache ANT bin folder path:

Cocos2d console requesting ANT bin folder path
Figure 5. Cocos2d-console requesting ANT bin folder path

After including the requested paths, reopen the command prompt (cmd.exe).

For this action is necessary to use cocos2d-console commands.

4. Type cmd.exe to go to the command prompt (cocos2d-console commands can only be issued from here) and open the framework folder again:
cd C:\Users\intel-user\Desktop\cocos2d-x-3.3rc0

In the step below we will create a new Cocos2d-x project:
cocos new MyGame –p com.Project.MyGame –l cpp –d Project

Created Cocos2d-x project
Figure 6. Created Cocos2d-x project

Here are quick explanations of the parameters:

  • new: creates a new project and must be followed by the name of the project (in the example, MyGame)
  • -p: defines package name
  • -l: select programming language. The value can be cpp or lua
  • -d: directory where the framework will create the project structure.

If everything went all right, your project will be created in the Project folder, in the directory where framework was extracted.

MyGame directory structure
Figure 7. MyGame directory structure

The created project contains the base code of the game (Classes), the resources (images, audio, etc.), and one project for each framework-supported platform.

Build Android* Apps

Requirements

  • You need to configure all the environment variables for building Android app games (Android SDK, Android NDK, and ANT). If you have not done this step yet, please see the "Creating your first game" section of this article.
  • Java Development Kit (JDK) installed

Note: Cocos2d-console uses the javac command to build for Android, because of this is necessary to add JAVA_HOME environment variable (JDK path).

1. We are going to compile our game for more than one architecture, since the framework doesn’t compile for x86 and armeabi-v7a by default. Edit the Application.mk file located in:
C:\Users\intel-user\Desktop\cocos2d-x-3.3rc0\Project\MyGame\proj.android\jni

Application.mk location
Figure 8. Application.mk location

2. Add the following line to the file:
APP_ABI := armeabi armeabi-v7a x86

Application.mk after
Figure 9. Application.mk after APP_ABI line added

Now that we added our targeted architectures, let’s compile our game.

3. Using the command prompt, go to the framework folder:
cd C:\Users\intel-user\Desktop\cocos2d-x-3.3rc0

4. Execute the command below to compile and run the game for Android.
cocos run –s Project\MyGame –p android

Executing compiling and running the game on Android
Figure 10. Executing command to compile and run the game on Android

  • run: compile and run the project
  • -s: path to project folder
  • -p: selected platform

Note: To compile only, enter: cocos compile –s Project\MyGame –p android

If everything worked properly, the cocos2d-console command will use adb (if configured in environment variables) to install the APK file in a connected device or initialized emulator. If they aren’t available, the command will wait for a device or an emulator to become available, like the picture below:

Command waiting for device or initialized emulator
Figure 11. Command waiting for device or initialized emulator

If you have initialized an emulator or connected a device, this screen will appear:

Game screen on Android platform
Figure 12. Game screen on Android* platform

Build Win32 Apps (for Windows 7 or Windows 8 Desktop Mode)

You will need Microsoft Visual Studio 2012* or later to build.

1. Using the command prompt (cmd.exe), go to the folder where framework was extracted:
cd C:\Users\intel-user\Desktop\cocos2d-x-3.3rc0

2. Execute the following command to compile and run the game on Windows:
cocos run –s Project\MyGame –p win32

Executing compiling and running the game on Windows
Figure 13. Executing command to compile and run the game on Windows

Here are quick explanations of the parameters:

  • run: compile and run the selected project
  • -s: path to project folder
  • -p: selected platform

Note: To compile only, use "compile" instead of "run", as follows:
cocos compile –s Project\MyGame –p win32

After executing the run command, you will see the following screen if everything worked ok:

Game screen in Windows platform
Figure 14. Game screen on Windows platform

It is possible to use Visual Studio to compile and run the game project:

1. Inside the Project directory, open with Visual Studio MyGame.sln file in the proj.win32 folder.

Win32 project directory structure
Figure 15. Win32 project directory structure

2. To compile the project, press F6 (or Build menu > Build Solution) and press F5 to execute it (or Debug menu > Start Debugging). After building and executing, you should see the same screen presented after the console steps.

Win32 project opened in Visual Studio
Figure 16. Win32 project opened in Visual Studio

Now you know how to create your game and compile it for Android (x86 and ARM), Windows 7, and Windows 8 (desktop mode).

References

The source code of Cocos2d-x framework is granted under the MIT License, and it be can be found on GitHub*.

Cocos2d-x and its documentation

cocos2d-console

Note: At this time, the release version of Cocos2d-x 3.3 has an issue during project creation which does not allow users to create projects (check for details). The problem has been fixed in the latest pre-release, but is not available on the Cocos2d-x latest release yet.

For more complete information about compiler optimizations, see our Optimization Notice.