Cocos2d-x Project Setup and Cleanup


In this post I will describe how to create a new project in cocos2d-x using the cocos command line interface. The project created using the cocos command is a “Hello World” demo application that both provides some game framework initialization and a generic scene with some basic functionality. In this post I will also describe how to cleanup the demo project so that it can be used to create a new game.

For the instructions in this post I have decided to use OS X, but the methodology described here can also be used on Windows, except that you will then be using Visual Studio or Eclipse instead of XCode.

It is assumed that you have installed and configured cocos2d-x in your development system. If you need help with that please check my previous posts for Linux and for Mac & Windows setup.

Create a new cocos2d-x project

Suppose that we want to create a game named “Space Monkey”. We would start by using the cocos command to create a new project. Open the command line interface (terminal in OSX and Linux, command interface in Windows) and type the following.

$ cocos new CRBSpaceMonkey -l cpp -d ./CodeBuildRun

The cocos command above can be broken down as follows:

  • cocos new – command to create a new project
  • CBRSpaceMonkey – The name of the project to create
  • -l cpp – Specifies the development language that will be used to develop the game. The “cpp” options means C++. Other options are “lua” or “js” for JavaScript.
  • -d ./CodeBuildRun – Indicates the directory where the project will be created.

The output of the command will be something like this:


Build the generated project

Launch XCode and open the generated iOS/mac project located in the following directory


Once the project is loaded in XCode you should see the following source code and resources file hierarchy:


Click on the issue navigator ( the icon with the warning sign highlighted in blue in the image below) and you will find that there is a warning message indicating that the project settings need to be updated.


Double click in the warning and you will be presented with a list of changes that would be applied to the project as shown below.

One of the major changes to the project through this update is that the earlier supported iOS version for the game will now be 8.0. This means that old devices with earlier versions of iOS will not be able to run your game if you choose to update the project settings.

If you decide to update your project settings then click on “Perform Changes”.


Build your project and run it. The demo application will be displayed as shown in the image below.


Add a new Scene to the project

A game scene can be thought of as one of the screens in  your game (there is really more to it and if you want to learn more about what a scene is you can read this). The scene in the generated demo game  displays the cocos2d-x logo, the “Hello World” message and the “close” button that you can see in the image above. All these resources are not very likely to be re-used in your real game so we will remove them in the next section.

The scene in the game source code is defined in a class named “HelloWorld”. I prefer to have a  scene with a better name that is more descriptive of the particular stage of the game. We will create a new game scene that will replace the HelloWorld class.

In XCode create a new C++ file in the “Classes” directory.



Let’s name the file “SpaceScene”. Make sure that the checkbox to create a header file is selected, as shown in the image below.


In the next dialog box, verify that the C++ files will be created in the “Classes” directory and that they are associated to both the Mobile and Desktop targets (see image below).


The C++ files created by XCode are practically empty. We need to create a class for our new scene so we will need to add some code to those files. The code that we will add to the new scene is the minimum necessary to create a scene. This code can be reused for every new scene that you add to your game. You would need to change the class name though.

Open the file “SpaceScene.hpp” and replace it’s contents with the following code:

#ifndef SpaceScene_hpp
#define SpaceScene_hpp

#include "cocos2d.h"

class SpaceScene : public cocos2d::Layer
    static cocos2d::Scene* createScene();


    virtual bool init();

#endif /* SpaceScene_hpp */

Replace the contents of “SpaceScene.cpp” with the following.

#include "SpaceScene.hpp"


Scene* SpaceScene::createScene()
    auto scene = Scene::create();
    auto layer = SpaceScene::create();

    return scene;

bool SpaceScene::init()
    if ( !Layer::init() )
        return false;

    return true;

In order to replace the HelloWorld scene with the new SpaceScene some changes need to be made to the AppDelegate.cpp file. Open this file in the editor and do the following changes:

1) At the top of the file, include the SpaceScene.hpp header file instead of HelloWorld.h.

#include "AppDelegate.h"
#include "SpaceScene.hpp"

Within function AppDelegate::applicationDidFinishLaunching(), find the following code:

// create a scene. it's an autorelease object
auto scene = HelloWolrd::createScene();

and replace it with the following code. The change is to create an instance of SpaceScene instead of the HelloWorld scene.

// create a scene. it's an autorelease object
auto scene = SpaceScene::createScene();

If you run the game now you will see a blank screen like the one shown below. You should now be able to start implementing the behaviour that you want for this scene.


Project Cleanup

At this point we do not need the HelloWorld scene so we can delete it. We should also delete the resources that we don’t need.

in XCode, select the files that we don’t need anymore and delete them



With all the changes described in this post, you should now have a functional cocos2d-x project that does not include unnecessary resources. The project now has an empty scene that is ready for you to start developing your game.

2 thoughts on “Cocos2d-x Project Setup and Cleanup

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