Sunday, March 10, 2013

Cocos2d-html5 (Part 1 - Introduction)

Hi there,

In this series of posts I'm going to show how to use the html5 version of the popular cocos2d framework, called "cocos2d-html5".

I'll use version 2.1.1, which has now feature parity between most variants, namely: cocos2d, cocos2d-x and cocos2d-html5. In this particular post I'm just going to setup everything in Windows 8 and prepare the placeholder for future posts.

You should check the homepage for this project at: It includes some info, tutorials and download links.

You may opt to download the cutting-edge version from the github repository or one of the stable(ish) releases.

  • For this tutorial I'll use the github version. You can clone the repository or download the zip, but I recommend the first option, as it'll also download the related projects (namely the samples).

Don't worry if you've never used Git before. The GitHub Windows client is as simple as it gets, and with literally one-click setups the project on disk.

  • You need to setup a web-server to fully use Cocos2d-html5. As I'm mostly a Windows developer  I'm going to use IIS 8 for it.

  • Under Default Web Site create a new Application called "cocos2dhtml5", pointing it to the repository on the disk (probably in: "c:\Users\<Your user>\Documents\GitHub\cocos2d-html5")

  • Open a Browser window and point it at: "http://localhost/cocos2dhtml5/index.html".
  • In windows 7/8 it's likely that you'll get an HTTP 401.3 Error

    • If so, you need to add the IUSR and IIS_IUSRS groups in the security settings of the folder. 

  • You should now be able to see the starting page of cocos2d-html5.

  • You can explore the demos to really understand the capabilities of cocos2d-html5. Unfortunately, if you open the tests, you can see that some of them don't work. If you inspect the HTTP traffic you see lots of 404 over there. Basically IIS is not recognizing most of the extensions used (as they're not standard): fnt, plist, ccbi, pfx, etc.
  • Fortunately, since IIS 7, we can define additional mime-types through web.config. Thus, create a "web.config" file in the root of the repository with the following content:
<?xml version="1.0" encoding="UTF-8"?>
            <mimeMap fileExtension=".plist" mimeType="text/xml" />
            <mimeMap fileExtension=".tmx" mimeType="text/xml" /> 
            <mimeMap fileExtension=".tsx" mimeType="text/xml" /> 
            <mimeMap fileExtension=".ccb" mimeType="text/xml" />
            <mimeMap fileExtension=".bgm" mimeType="text/xml" />
            <mimeMap fileExtension=".ccbi" mimeType="text/xml" />
            <mimeMap fileExtension=".fnt" mimeType="text/plain" />
  • Refresh the webpage. You should now be able to view the remaining samples. 

  • It's very common to use the "Hello World" demo as a placeholder for your project, so just open it. You should see something like this:
  • Copy the "HelloHTML5World" folder in file explorer, naming the new folder MyFirstGame (or whatever you prefer).

  • Now take a look at the structure of the new project

In this post I'm not going to delve into great detail, but the flow is basically:

    • "index.html" is the webpage where all starts. It: 
      • Declares an HTML5 canvas
      • References the file: "cocos2d.js"
    • "cocos2d.js" is the main configuration of the engine. It:
      • Is used to configure certain settings of the engine
      • References all the JS files used in the project
      • Bootstrapps everything, launching your application, in this case "MyApp.js"
    • "MyApp.js" is your application itself. In the Hello World template it already has a scene setup up, several animations and some event handlers. I've removed most code so that it looks like this:
var Helloworld = cc.Layer.extend({

    helloLabel: null,

    init:function () {
        var selfPointer = this;

        var size = cc.Director.getInstance().getWinSize();
        var layerBackground = cc.LayerColor.create(
            new cc.Color4B(0, 0, 0, 255), 800, 600);
        this.helloLabel = cc.LabelTTF.create("My First Game", "Arial", 38);
        this.helloLabel.setPosition(cc.p(size.width / 2, 500));
        return true;

var HelloWorldScene = cc.Scene.extend({
    onEnter:function () {
        var layer = new Helloworld();

It's just a black background with some text on it.

I've also uploaded so you can see it in "motion" here. Not really interesting, but a placeholder nonetheless.

No comments:

Post a Comment