Cocos2d-x installation and setup on Linux


If your preferred development environment is based on a linux computer then you may be interested in this blog post because I will describe, step by step, how to install and setup cocos2d-x on linux.

The installation steps in this tutorial are based on a fresh install of Ubuntu Linux version 16.04.1. I am also using the latest version of Cocos2d-x at the time of this writing, which is version 3.13.1. If you have different versions of linux the installation steps may vary slightly but this guide will still be useful as the workflow would be similar.

Download Cocos2d-x

Lets start by downloading Cocos2d-x V3.13.1 from this link. Cocos2d-x will be downloaded as a .zip file and it will need to be decompressed. The file will be downloaded to your “Downloads” folder in Ubuntu. I suggest that you move the downloaded file to a different location such as a new directory named “Projects/Cocos”. Once the file is moved, you can decompress it inside the same directory. Use the following terminal commands:

$ mkdir -p ~/Projects/Cocos
$ mv ~/Downloads/ ~/Projects/Cocos
$ cd ~/Projects/Cocos
$ unzip


Configure Cocos2d-x

Now that we have all the source code decompressed, setup the cocos2d-x environment variables by running a python setup script. The setup script requires python 2.7 in order to run. This version of python is included when Ubuntu is installed. If you have any other distribution of linux, make sure you have the required version of python installed.

$ cd ~/Projects/Cocos/cocos2d-x-3.13.1
$ python

The setup script will ask you to enter the path to the Android SDK, the NDK and Ant, which are only necessary if you develop games for the Android operating system. If you don’t have such tools intalled, you can press “Enter” whenever the setup script ask you to enter the Android tools paths.

Once the setup script has finished configuring the cocos2d-x environment variables, you need to run the following command so that the environment variables take effect:

$ source ~/.bashrc

Now cocos2d-x should be setup, but before you can invoke the cocos command from the terminal you need to make it executable using the following commands:

$ cd ~/Projects/Cocos/cocos2d-x-3.13.1/tools/cocos2d-console/bin
$ chmod +x cocos

You should now be able to run the cocos command from the terminal.

$ cocos

Note that the very first time that you run the cocos command you will be asked whether you want to share usage data with the cocos team (see screenshot below). Type “N” if you don’t agree to send usage data or “Y” if you agree.

Screen Shot 2016-10-04 at 11.51.46 PM.png

Next you will see a list of available cocos commands. We will only use two of those commands during this tutorial:

  • cocos new  : this command will create a new cocos template for you to use as a base for your game.
  • cocos run : will build and run your game.


Install dependencies

Before you can build the game engine or any game that you build on top of it, some linux packages need to be installed. Cocos2d-x provides a couple of scripts that can install all the dependencies for you.

The first thing to do in order to run the installation scripts is to make them executable:

$ chmod +x ~/Projects/Cocos/cocos2d-x-3.13.1/build/
$ chmod +x ~/Projects/Cocos/cocos2d-x-3.13.1/tools/travis-scripts/

The next step is to run the script as a super user, so make sure that you run the following commands with “sudo”. The script will automatically be executed as part of

$ sudo apt-get update
$ cd ~/Projects/Cocos/cocos2d-x-3.13.1/build
$ sudo ./

A summary of dependencies to install will be presented to you and you will be asked to confirm if you want to install them. Select “Yes” to continue.

Once the scripts finish running, you will have all dependencies installed.

Create a new game

Alright, cocos2d-x should now be installed in your system along with all its dependencies. Now we should test it by creating a game, building it and running it!. Type this in the terminal:

$ cd ~/Projects/Cocos
$ cocos new TestGame -l cpp

The cocos new command creates a new cross platform game with platform specific code for Android, iOS, Mac OSX, Windows, etc.. The game also includes common generic code that is shared among platforms, i.e. non platform specific code. We will get into the details about all this in a future blog post.

The “-l cpp” argument tells cocos to use C++ as the development language for the game.

Run the game

To run the game on linux type the following commands in the terminal.

$ cocos run -s TestGame -p linux

the cocos run command will build the game specified with the “-s” switch and execute it for the platform indicated with the “-p” switch.

The game will take a long time to compile the very first time we build it because it needs to build the cocos2d-x game engine and then the game. Subsequent builds will be faster since the game engine will not need to be recompiled unless you made changes to it, and even if you did only the parts that changed will be re-built.

Once the game is built cocos will execute it and you will see a window like this:

Screen Shot 2016-10-05 at 12.57.11 AM.png

If you see the game running you have installed and setup cocos on your linux computer. Now you can start creating a game!



4 thoughts on “Cocos2d-x installation and setup on Linux

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s