by ryanwilliams

ryanwilliams / cocos2d-javascript

An HTML5 / JavaScript port of the Cocos2D graphics engine

442 Stars 63 Forks Last release: Not found MIT License 517 Commits 3 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

This is no longer supported. You probably want instead.

What is Cocos2D JavaScript?

Cocos2D JavaScript is an HTML5 port of Cocos2D for iPhone. It is a 2D graphics engine which allows rapid development of 2D games and graphical applications which can run in any modern Web browser without the need for third-party plug-ins such as Adobe Flash.


We don't currently support running multiple versions of Cocos2D JavaScript on the same machine so you should first uninstall the old version before installing a new version.

If you really do want to run multiple versions on the same machine you will have to do a manual install and launch the appropriate 'cocos' command directly.

To upgrade your project from v0.1 you should create a new project using the 'cocos' command and then copy the src folder from your old project into the new one. There may be backwards incompatibilities which you'll need to debug.


Follow the instructions for your given platform or skip ahead to 'manual installation' if you want to install from git.


Download and launch the installer.

Mac OS X

Download the DMG and launch the installer.

Linux or Mac OS X using Node.js and NPM

If you have Node.js and npm installed you can install Cocos2D JavaScript as a global package.

For the latest stable release:

npm install -g cocos2d

For the latest unstable:

npm install -g [email protected]

Linux or Mac OS X using Zip archive

If you don't have, or don't want to use npm, you can install by downloading the latest Zip.

Then from your terminal run

sudo ./
. The script will copy Cocos2D JavaScript to a global location of your choice and symlink the executable to /usr/local/bin/cocos

Manual Installation (all platforms)

You don't need to use the installer if you don't want to. You can download the latest ZIP or checkout the latest version from github.

If you checkout from github and don't have Node.js installed, be sure to also get the git submodule which includes precompiled Node.js binaries.

git submodule update --init

You can put Cocos2D JavaScript anywhere you want and from there use the 'cocos', 'cocos.bat' or .EXEs in bin/ to launch the various commands.

Creating your first project

On Windows use the 'Create project' shortcut from your start menu to create and select a location for your new project.

On Linux and Mac OS X open your terminal and run:

cocos new ~/my_first_project

This will create a bare-bones project which simply draws the project name in the centre of the screen.

To test that it's working, on Windows double click the 'Serve project' shortcut in your project's folder.

On Linux and Mac OS X from your terminal run:

cd ~/my_first_project
cocos server

Now visit and with a bit of luck you'll have something showing.


Cocos2D JavaScript uses a package called Jah to handle development and compilation. All the code you write will be in separate JavaScript files which you can organise any way you wish. When it comes to deploying your application, Jah will compile these files down into a small number of JavaScript files for you to put on your webserver.

The entry point for the code is the file src/main.js where you'll find an

function which will be called when your application starts.

The HTML for the page sent by the development server is at public/index.html.template and can be customised if you need any special alterations to it.

Compiling your application

You should never use the development server in production. It's slow and insecure. Instead you will compile your application into a handful of JavaScript files. You'll get one file for each library that you use. So normally you'll end up with three files: jah.js, cocos2d.js and application.js. The first two are standard libraries that you can reuse in multiple applications. While the third file is your application code.

To compile your project on Windows double click the 'Compile project' shortcut in your project's folder.

To compile on Linux or Mac OS X open your terminal and run:

cd ~/my_first_project
cocos make

The files will be written to build/. You can run the resulting .js files through a JavaScript minifier if you so choose. You will also get a good reduction in size if your Web server is configured to gzip JavaScript files.

Browser Support

Everything is designed to work in Firefox 4, Chrome, Safari, Opera and IE9+. If that is not the case then please file a bug report.


Documentation can be viewed online at

If you wish to generate the documentation yourself you need to follow these steps.

Download JsDoc 2.3 (or 2.4) from

Copy that to /usr/local/jsdoc-toolkit or wherever you like and then run:

JSDOC_HOME=/usr/local/jsdoc-toolkit ./bin/jsdoc

The documentation will appear in the 'docs' directory.


Cocos2D JavaScript is released under the MIT license. See LICENSE for more details.

© 2010-2011 Ryan Williams [email protected]


We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.