Getting Started with Cocos2d-html5 (Out of date, it will be updated soon)¶

Introduction¶

Cocos2D-html5 is the latest spin off from Cocos2D-X team. It is written in Javascript for HTML5 compliant browsers. The API is derived from Cocos2d-X, therefor if you have any experience in Cocos2d game engines, you already know how to use Cocos2d-html5. If you never used Cocos2d game engine before, don't worry, this article will teach you everything you need to know to get started.

Because Cocos2D-html5 is based on web, you can write your app on any platform as long as you have access to a text editor, and because its web based, your app can be run on any device that have access to a web browser (HTML5 compliant one)! How convenient, and that is why, "The future is in your browser".

Javascript?¶

While there are concerns over the "scripting language" efficiency, sure it is slower than c++, but technologies like V8 Javascript engine and hardware accelerated canvas rendering made game development possible. At this time, the hardware found on mobile phones are still lacking some "oomph" to run javascript efficiently, however, the team of Cocos2d-x are working on something called "Javascript binding for Cocos2d". What that means is your very same code running on Cocos2d-html5 engine can work flawlessly on Cocos2d-X and Cocos2d-iPhone without or with little modification. And all that translates to "almost native fast on mobile phones".

In the future, we will see mobile phones to be very powerful, you will starting to see more phones running quad core multi-GHz cpu, with dedicated graphics chip. We expect them to run html5 games just as fine as desktops

What about WebGL?¶

WebGL means OpenGL for the web, which means 3d hardware acceleration.
At the time of this writing, WebGL is still yet to be implemented by Cocos2d-html5.
When mobile phones adopts WebGL as standard, Cocos2d-html5 games will run flawlessly and only limited by game designer's imagination!
Cocos2d-html5 will have WebGL support by version 2.1.0.

Installing Cocos2d-html5¶

Installing Cocos2d-html5 is as easy as extracting it, and run the "index.html"!

1. Download Cocos2d-html5 from the official website at "html5.cocos2d-x.org"
2. Extract the files to any directory
3. Open "index.html" to run the sample codes
4. ???
5. Profit!

If the sample codes stuck at a black blank screen, don't panick, you are probably using browser that blocks certain API for local files for security reason.

There are 2 ways around that:
1. Use Firefox 12 ,Opera or Safari, these browsers are friendlier with local files.
2. Install a webserver on your computer

Installing a webserver (optional)¶

You have many options here:

• XAMPP : for windows, Mac, Linux.
• WAMP : for windows
• MAMP : for mac

1. Download one of your choice,
2. Follow the instruction to install,
3. Find the installed directory,
4. Find the root directory, it should be something like "htdocs" or "www"
5. Copy the extracted Cocos2d-html5 files inside
6. Point your browser to "localhost"

You should be able to see something like this:

If you still have trouble, see the webserver trouble shooting guide

Debugging your code¶

Debugging Javascript code should be familiar for web developers. Modern browsers have built in tools to help you develop Javascript apps.

On Most browsers, Press F12 to open up the Developer's tools,
(On Opera, press Ctrl+ Shift + i).
(On Safari, go to preference, then Advanced, then tick "Show Develop menu in menu bar". to open the developer tool, right click and choose "inspect elements")

Google Chrome is recommended as it is the most convenient and packed with features.
For details of how to use Chrome Developer Tools, see the docs here: https://developers.google.com/chrome-developer-tools/docs/elements

From there, you can access the console, which will output any errors made inside the game engine. You can also enter Javascript commands into the console as you please

Spicing up the Hello World¶

The default Hello World sample code draws a cocos2d-html5 logo background and the word "Hello World", how boring.

This is a mini tutorial to Cocos2d-html5 to make the Hello World template more interesting.

Open the "Helloworld.js" located in HelloWorld directory.

The first thing you will notice is this
Line 27: var Helloworld = cc.Layer.extend()
This is the Cocos2d-html5 way of object inheritance, it comes from John Resig's javascript Inheritance, in this case it means we are defining a new class from CCLayer called Helloworld.

Everything else should feel familiar to anyone who used Cocos2d before, except
Line 38: this._super()
This simply means run the parent class's version of this function.

Lets get right into it!¶

Find line 74 where it initialize the background sprite
Line 74: this.pSprite = cc.Sprite.spriteWithFile("Resources/HelloWorld.png");

And lets turn it upside down by rotating it 180 degrees, add this after line 74
this.pSprite.setRotation();

Now lets make it smaller to start with, later we will add an animation to make it go back to original state,

// add "HelloWorld" splash screen"
this.pSprite = cc.Sprite.spriteWithFile("Resources/HelloWorld.png");
this.pSprite.setRotation(180);
this.pSprite.setScale(0.2);
this.pSprite.setAnchorPoint(cc.ccp(0.5, 0.5));
this.pSprite.setPosition(cc.ccp(size.width / 2, size.height / 2));

Preview our changes, it should look like this now

Animating the sprite¶

First, we have to define our actions, we want to scale it to its original size, so lets define our scale action:
var scaleTo = cc.ScaleTo.actionWithDuration(2, 1, 1);
Here we declared an action with duration of 2 seconds, and scaling to 100% size for both width and height
Now you have to make the sprite run the action

// add "HelloWorld" splash screen"
this.pSprite = cc.Sprite.spriteWithFile("Resources/HelloWorld.png");
this.pSprite.setRotation(180);
this.pSprite.setScale(0.2);
this.pSprite.setAnchorPoint(cc.ccp(0.5, 0.5));
this.pSprite.setPosition(cc.ccp(size.width / 2, size.height / 2));

var scaleTo = cc.ScaleTo.actionWithDuration(2, 1, 1);
this.pSprite.runAction(scaleTo);

View your changes, you should see the sprite scaling up linearly. Close but no cigar, so lets polish up the action with "ActionEase";

// add "HelloWorld" splash screen"
this.pSprite = cc.Sprite.spriteWithFile("Resources/HelloWorld.png");
this.pSprite.setRotation(180);
this.pSprite.setScale(0.2);
this.pSprite.setAnchorPoint(cc.ccp(0.5, 0.5));
this.pSprite.setPosition(cc.ccp(size.width / 2, size.height / 2));

var scaleTo = cc.ScaleTo.actionWithDuration(2, 0.8, 0.8);
var EaseScaleTo = cc.EaseElasticOut.actionWithAction(scaleTo, 0.4);
this.pSprite.runAction(EaseScaleTo);

Nice, this should gives you a pop up in your face feeling
Lets do the same to rotate it back to original orientation:

// add "HelloWorld" splash screen"
this.pSprite = cc.Sprite.spriteWithFile("Resources/HelloWorld.png");
this.pSprite.setRotation(180);
this.pSprite.setScale(0.2);
this.pSprite.setAnchorPoint(cc.ccp(0.5, 0.5));
this.pSprite.setPosition(cc.ccp(size.width / 2, size.height / 2));

var scaleTo = cc.ScaleTo.actionWithDuration(2, 0.8, 0.8);
var EaseScaleTo = cc.EaseElasticOut.actionWithAction(scaleTo, 0.4);
this.pSprite.runAction(EaseScaleTo);

var rotateBy = cc.RotateBy.actionWithDuration(2, 180);
var EaseRotateBy = cc.EaseElasticOut.actionWithAction(rotateBy, 0.4);
this.pSprite.runAction(EaseRotateBy);

Impressive intro! But what if we want to play one animation after another? No problem

// add "HelloWorld" splash screen"
this.pSprite = cc.Sprite.spriteWithFile("Resources/HelloWorld.png");
this.pSprite.setRotation(180);
this.pSprite.setScale(0.2);
this.pSprite.setAnchorPoint(cc.ccp(0.5, 0.5));
this.pSprite.setPosition(cc.ccp(size.width / 2, size.height / 2));

var scaleTo = cc.ScaleTo.actionWithDuration(2, 0.8, 0.8);
var EaseScaleTo = cc.EaseElasticOut.actionWithAction(scaleTo, 0.4);
this.pSprite.runAction(EaseScaleTo);

var rotateBy = cc.RotateBy.actionWithDuration(2, 180);
var EaseRotateBy = cc.EaseElasticOut.actionWithAction(rotateBy, 0.4);
this.pSprite.runAction(EaseRotateBy);
this.pSprite.runAction(cc.Sequence.actions(EaseRotateBy,EaseScaleTo));

Congratulation, you just learned how to turn a boring HelloWorld sample code into slightly less boring animated HelloWorld! You could probably write your ppt in Cocos2d-html5 now!

Conclusion¶

Well I hope you’ve found this brief introduction to Cocos2d-html5 helpful. And hope you feel that Cocos2d-html5 is an easy to setup, easy to learn, and easy to use framework. You can finish your games efficiently with Cocos2d-html5, and run it cross browsers.

If you’ve enjoyed this let me know via Twitter: http://www.twitter.com/cocos2dx, it’s always good to say hello!