BoxQuest Sample: Start to Finish

BoxQuest Sample: Start to Finish
0.0 0


Hello all, I just wanted to re-share a sample I made. The reason for the re-share is that I’ve added a ‘tutorials’ section which breaks down the full sample into four smaller parts:

  • A basic Cocos2d-HTML5 skeleton.
  • Leveraging Sprites and TMX Tile maps.
  • Physics with Box2DWeb and Web Workers.
  • Touch controls with Freewill.js.

There is a PDF guide for the tutorials as well that tries to go line-by-line explaining the approaches taken.

The sample is by no means complete, but I thought it in a good place to share. I also plan on revisiting the touch controls to see how the Cocos2d-HTML5 implementation is doing (I haven’t attempted the built-in approach since my initial development, so it may very well be suitable at this point.)

The resources can be found here (check the ‘tutorials’ folder for the guide/sections):

If you have any feedback, or are doing any BlackBerry development, please don’t hesitate to reach out to me directly (

Cheers all!


Thanks Erik,

I don’t have a BB but some of the things you’ve looked at, i.e WebWorkers and also Box2DWeb sound very interesting.

I noticed in your that you had issues with Box2DWeb because of the calls to “update”. I’ve already posted an “issue” on GitHub about “update” not being called at regular intervals, and this is supposed to be addressed when cocos2d is refactored at some time in the future.
From what I can see, calls to “update” are sometimes delayed by quite a while e.g. several hundred milliseconds, and sometimes occur with “delta time” of zero.

The long delays make animation jumpy at times.

I’m not sure WebWorkers is a general purpose solution to this issue for cocos2d-HTML5, because of support on various platforms. I know WebWorkers is only available in IE10 and AFIK cocos2d-html5 is supposed to run on IE9. So I"m waiting for the cocos2d-html5 team to do their own fix for the update issue :wink:

I wonder why you chose to use Box2DWeb instead of the Box2D that’s part of cocos2d-html ?? Is this a Blackberry thing, or is there a performance increase etc??




there are bunch of box2d ports to JS, none of them are handwritten, and are all auto generated. thus poor performance.

in contrary, Chipmunk js was handwritten, and with optimization in mind, it is about twice as fast as any box2d js generated ports

About the update cycle, ye we are fully aware of that, and we are looking for a way to solve it.
This issue may not be easy to solve, as it is more of a language and browser thing than game engine, js is single threaded, its timing is terribad, the garbage collector is uncontrollable, and when it does its things, it spikes the game loop
Webworker might help with this issue by moving physics to another thread, but the cost of sending and receiving large objects between thread may not provide too much benefit, also the issue with ie9 and some mobile browsers

As for now, I recommend for physics games that you spawn a new “setInterval” for physics calculation, and using fixed timestep for physics loop


Thanks for that info, the update timing you mentioned is certainly in line with what I was seeing. Instead of Web Workers, leveraging setInterval as per Hao’s suggestion may very well do the trick. Web Workers were more of a personal preference primarily for the sake of having another sample with Web Workers out there.

Very large data transfers between Web Workers could potentially offset the gains of separate-thread calculations, I’ll try to see if I notice any difference. In BoxQuest, the data transfer is pretty limited (i.e. XY-coords and rotation) so my guess is that the calculations gains are greater than the transfer cost. I’ll see if I can get some hard numbers for an optimal approach.

Regarding Box2DWeb, I didn’t know about submodules in Github until recently and it was my way of ensuring that the physics engine distributed with the sample would work. Now that Cocos2d-HTML5 is included as a submodule, I’ll take a look at updating the sample.

That being said, I’m a bit confused at the inclusion of Box2D and Chipmunk in the Cocos2d-HTML5 framework; are these intended as a “use one or the other” scenario? In my initial endeavors, the Cocos config always had a flag for including Box2D (or not), which I was assuming was based on Box2DWeb. How does Chipmunk fit into the framework, is it an alternate (but optimal) physics engine that’s also included or am I misunderstanding?


It is better to include box2d and chipmunk using submodule. However, I can’t find the right repo in github.

Both box2d and chipmunk are components.
Chipmunk is recommended when you want to publish your code to JSB.
Otherwise, they are the same.


Yes Chipmunk is an alternate physics engine
and right now, it is recommended as its smaller, faster and better maintained by any box2d js ports.