Getting started with Cocos2D (Updated for Cocos2d-x V3.7.1)

Getting started with Cocos2D (Updated for Cocos2d-x V3.7.1)

Postby BenChang » Wed Sep 24, 2014 2:10 pm

A step-by-step guide for downloading and installing cocos2d-x v3.7.1. The pictures are for Windows, but the process for other OS's is basically the same, or easier.


Step 1: Download
Click the link for "Download V3.7.1". This will download a zip file with the complete Cocos2D development tools, samples, and source code. It contains the C++ version, the Lua scripting bindings, and the JavaScript version, Cocos2D-js.

(The "Cocos" application in the middle column is a launcher for Cocos Studio and some other tools, which lets you do visual scene layout, GUI's, and animation editing for Cocos. "SDKBox" is a set of integration libraries for Cocos for analytics, Facebook, in-app purchases, etc. )


Step 2: Unzip
One you have the zip file downloaded, move it out of your downloads folder and unzip it. I put mine in "My Documents/GameDev1".


Cocos2D folder contents

the "tests" folder contains examples for each language, demo'ing all the features of the engine.
After you've unzipped it, you can delete the zip file if you want to save space. We'll use that later.

The "" Python script is what you'll run to install and configure Cocos2D. In order to run it you need Python, so first let's install Python. If you already have Python 2.7 installed, you can skip ahead to step 5. Mac users should have python already, it comes with OSX. Same for Ubuntu, Debian, and many other Linux distros.


Step 3 (Windows only: Get Python 2.7

Download Python 2.7.10 (NOTE: Python 3.x won't work for this)


Step 4: Run the Python installer and set the Path option
When the installer gets to the screen that says "Customize Python 2.7.10", scroll down and find the option "Add python.exe to Path". Click the popup menu next to it and set it to be installed. This will let you just run the command "python" from the command prompt, and is necessary for the Cocos installation and console tools to work.

Step 5: Open the Command Prompt


Cocos uses the command line to create new projects and compile and run projects.

On Windows, click on the Start menu and type in 'cmd' to open the command line.
On OSX, find the "Terminal" application in the /Applications/Utilities folder.
On Linux, the terminal should be easily available from the application menus in whatever distro you're using.

Quick command list (Windows)
cd directory Change Directory. use this to go "into" a folder from where you currently are.
cd .. go up one level
dir print out a list of what's in the current directory
python run a python script
TAB tries to auto-complete a command based on what you've started typing. It will use the first match it finds, which is not always the one you want if multiple files start with the same few characters.
UP and DOWN cycle through past commands

Quick command list (OSX, Linux)
cd directory Change Directory. use this to go "into" a folder from where you currently are.
cd .. go up one level
cd go to your home directory
ls print out a list of what's in the current directory
pwd print out the Current Working Directory
python run a python script
TAB tries to auto-complete a command based on what you've started typing. if there are multiple possible matches, if will fill in as much as it can and then wait for you to type more
UP and DOWN cycle through past commands

Step 6: Go into the cocos2d-x-3.7.1 directory

Code: Select all
cd Documents
cd GameDev1
cd cocos2d-x-3.7.1

Code: Select all
cd Documents/GameDev1/cocos2d-x-3.7.1


Step 7: Run the script

Code: Select all

When it asks for the location for ANDROID_SDK, ANDROID_NDK, and ANT, just hit enter to skip. These are the Android development kit and tools, so if you don't have them installed just skip them. You can always install them later.


The output should looks something like this.


Step 8: Test the cocos console command
Open another Command Prompt and type
Code: Select all

It should print out the usage / parameters for the cocos command. If it says cocos is not found, try closing the command windows, open a new one, and run cocos again. If it still doesn't work, something went wrong in the install process.
If it says Python is not a command or not found, it means your system path doesn't include the python 2.7 directory so you'll need to edit your enviromment variables to include it.

[b]Creating a new Javascript cocos project[/b]
Create a new project named MyCocosGame with the language set to Javascript (js):
Code: Select all
cocos new -l js MyCocosGame

Running a Cocos project
Go into the MyCocosGame directory and run it in a web browser:
Code: Select all
cd MyCocosGame
cocos run -p web

Screen Shot 2015-09-03 at 10.28.05 AM.png

The Hello World cocos template in the browser.
Cocos launches a lightweight local web server running on your computer, so it can simulate the way the game will load when it's on a real, public web server. The web server that cocos runs is in the console in the background. Closing the browser window won't quit the web server, so if you want to quit it and get control back in the terminal window, just press Ctrl-C.

you can also build a windows exe:
Code: Select all
cocos run -p win32

Or build an Android app if you have the Android software development kit installed:
Code: Select all
cocos run -p android

Editing the code

Screen Shot 2015-09-03 at 11.02.57 AM.png

The first place to begin editing and experimenting is in src/app.js

For your first experiment, just try changing the text in the "Hello World" label in the middle of the screen. This is in app.js, around line 38.

Code: Select all
        // 3. add your codes below...
        // add a label shows "Hello World"
        // create and initialize a label
        var helloLabel = new cc.LabelTTF("Hello World", "Arial", 38);

change the text from "Hello World" to something else.

Code: Select all
        var helloLabel = new cc.LabelTTF("here's my first Cocos game", "Arial", 38);

and save your changes to app.js.

Viewing changes

Back in your web browser, reload the page. The new text should appear. If you just get the same version again, make sure you remembered to save your changes, and then try Force Reloading the page, and Disabling the Cache in your browser.

If you closed the browser window, open a new browser window and enter this URL:
Code: Select all

Or if you've quit or closed the background web server, just run
Code: Select all
cocos run -p web

from the project directory again.

Troubleshooting cache problems
A frequent problem when doing Cocos or other javascript web development is when you make changes but they don't appear in the browser. This is because web browsers cache documents, so if you reload a page and it hasn't changed, the browser will just load the cached version locally instead of taking the time to fetch it remotely again. This also includes media files, javascript files, everything. The most reliable way to prevent this from happening is to disable the cache. You can do this multiple ways:
  • Open a browser window in Incognito or Private Browsing mode. The cache is disabled for that window
  • Disable caching through the web developer tools. In Firefox and Chrome, there are settings in the Developer Tools to disable the cache. The cache may only be disabled while the developer tools window is open, and revert to normal when it's closed
  • Disable cache globally. You can do this in Firefox by going to
    Code: Select all
    , search for "cache", and set
    Code: Select all
    Code: Select all

Debugging javascript
Javascript tends to fail silently, so if there's a bug in your code, the most common thing to see is a black screen in your browser or see the game freeze, sometimes partway through loading. The errors are kept nicely out of sight by the browser in the web console and debugger. In Firefox you can access these from the Developer Tools:

Screen Shot 2015-09-03 at 11.32.57 AM.png

Screen Shot 2015-09-03 at 11.41.22 AM.png

The Console will print out any errors, and you can also use it to print out debugging information using the
Code: Select all
The Debugger will let you set breakpoints, step through code, inspect variables and objects, trace through the call stack, etc. We'll get into that in more detail later, as well as the debugger in WebStorm.

Troubleshooting Python installation (Windows only)
On Windows, you may get an error that Python can't be found, either when you try to install Cocos2d-x using "python", or when you try to use the cocos console command. On OSX and many Linux distros this shouldn't be a problem, since Python should come pre-installed.

If you know you do have Python 2.7 installed, and you get this kind of error, then this is usually because the PATH environment variable isn't set up to include its location, so the OS doesn't know where to look for it. The "Add python.exe to PATH" option in the Python installer should set this correctly, but if it doesn't, or it wasn't checked when you ran the installer, you can fix it manually. See [url=""]this post[/url], or use these images to add "C:\Python27" to the end of your "PATH" environment variable.



User avatar
Posts: 176
Joined: Mon Jan 17, 2011 4:48 pm

Return to Game Development

Who is online

Users browsing this forum: No registered users and 2 guests