Outdated Docs > Emscripten > Emscripten usage

Cocos2D-X’s Emscripten support allows games written in C*+ to be compiled to JavaScript and deployed directly to the web. The current status of the Emscripten support is that most of the tests in the TestCpp sample run, but there are still a handful of visual glitches.
h2. Getting Started
Here are the basic steps to follow to get the sample applications to build with Emscripten.
h3. Setup Emscripten
Before getting started, follow the tutorial on the Emscripten wiki. Cocos2D-X includes a submodule for Emscripten, but working through the tutorial first will ensure that you have all of Emscripten’s dependencies installed and configured.
h3. Get Cocos2D-X
Run the following commands from the terminal:

git clone https://github.com/cocos2d/cocos2d-x.git
git submodule update —init —recursive

h3. Compile Cocos2D-X & samples
Go to your Cocos2D-X tree, and run the following command:

make -f Makefile.emscripten -j 8

This will compile Cocos2D-X as well as all the samples. Once it’s done, you will find .js, .data and .html files in the proj.emscripten/bin/release directory, for example:

\$ ls -1 samples/Cpp/TestCpp/proj.emscripten/bin/release/

Briefly, .data files contain packed versions of all the assets needed for your game, .data.js contains an index for same. The TestCpp.js contains the compiled JavaScript output, and index.html is a simple page to just import all of the others.
Please note that it will not suffice to just point your browser to those files on the disk. The reason is that the .data file is retrieved via XmlHttpRequest, which is disallowed for files on your filesystem. Instead, you will need to copy these files to a webserver and look at them there. If you are using a Mac, you can copy them to a subdirectory of <sub>/Sites,\ and\ ensure\ that\ you\ have\ “Web\ Sharing”\ enabled\ in\ settings.\ Your</sub>/Sites directory will then be visible at http://localhost
The Emscripten build scripts follow the conventions of the Linux build scripts, and as such respond to many of the same inputs. For instance, to produce a debug build, you can execute

DEBUG=1 make -f Makefile.emscripten -j 8

Note, however, that when doing this one must be careful to ensure that intermediate object files were built in the same configuration as the desired output, since the DEBUG flag will enable code gated by the preprocessor. For example, if you have been doing debug builds and wish to do a normal release build, you would need to execute the following commands:

DEBUG=1 make -f Makefile.emscripten clean
make -f Makefile.emscripten -j 8

At present there is no standard build procedure for Emscripten apps, so this guide does not go into detailed advice on how to set up a new Cocos-Emscripten project, since best-practice has not yet been established. That said, the proj.emscripten directory under any of the C*+ samples is not a bad place to start.


The work of porting Cocos2D-X to Emscripten has really only just begun, and the current tree should be considered a work in progress. Some of the known limitations of the current codebase follow, but this should by no means be considered an exhaustive list:

  • Audio currently not supported.
  • Only PNG textures supported at present. Notably, no support for hardware compressed textures. Since desktop browsers do not support PVRTC, we should consider adding support for S3TC or similar.
  • TTF rendering with FreeType is slow. Recommend using bitmap fonts for now.
  • Does not yet validate with asm.js
  • Screen resolution currently hardcoded to workaround Emscripten not (yet) implementing the EGL_WIDTH and EGL_HEIGHT queries on eglQuerySurface.
  • Similarly, mouse offsets will be calculated incorrectly if the size of the screen is changed.

Closing Remarks

Emscripten has proven an extremely effective tool for compiling games to deploy to the web, and it’s super-exciting to add Cocos2D-X to the list of game-engines that can be targeted with this technique. Development on Emscripten enhancements will continue at https://github.com/j4m3z0r/cocos2d-x with changes periodically submitted back to mainline Cocos2D-X. Check in there for more recent updates, and we absolutely welcome collaborators.

Setup emscripten on Mac OS X

Setup Emscripten on Mac OS X Mountain Lion

Sign up for our newsletter to keep up with the latest developments, releases and updates for Cocos2d-x.