Debugging a BB10 WebWorks app: Cocos2d-x HTML5

December 26th at 12:00am

In a previous article I explained the steps necessary to build & Deploy a BlackBerry WebWorks Application. I'd like touch on how you can debug WebWorks when things don't work the way you expect. Over the last few weeks I've spent a few hours here and there preparing a JavaScript version of a game of mine (Pocket Bombs) so it could be ready at BB10's launch.

I found that I had issues when running the app on my Dev Alpha test device, and that's where things got a little trickly...

References:

 

Overview

I had written a game called PocketBombs for the iPhone about 18 months ago that I wanted to port to JavaScript. A port to JavaScript would allow the game to run on pretty much any device, and would be easy to package for BB10 using WebWorks. Since the game was written using cocos2d-iphone, I decided to use Cocos2d-x HTML5 for the JavaScript port for simplicity.

After getting everything to work on my desktop and validating app functionality using the browser on my Dev Alpha device I started the process to package the app for WebWorks. Unfortunately, it didn't work right off and I had to troubleshoot

 

Troubleshooting: Web Inspector

WebWorks makes available a very powerful tool for debugging: The WebInspector. If you enable web inspector on your Dev Alpha device (or simulator) it will allow you to use the Google Chrome browser to connect to your app that is running on the device and set breakpoints, inspect html and do all the cool things you have come to expect from the chrome debugger tools.

To enable WebInspector for your WebWorks compiled applications, be sure to include the -d switch instead of -g <keystorePassword>. This will allow you to hit a URL formatted like this: http://ip.address:1337 and enable a debugging session. You'll see a screen like this letting you pick your app from the list and start debugging:

WebInspector.png

 

Troubleshooting: App Initialization / Startup

While the Web Inspector is great for debugging issues with your running program, it doesn't do much (anything) to help you debug application initialization. There's no way to tell the program to halt execution and wait for a debugger to be attached, so if there are issues during the first few seconds of loading your app the debugging mechanisms get more primitive.

In my case I was able to run my app in the 'browser' fine, but when I packaged it as WebWorks I only saw a white screen. By the time I attached the Web Debugger it was too late: there were no error messages preserved to let me know what was going wrong. I had to resort to the old Standby for JS debugging: alert('') statements.

Using javascript alert statements like alert('started method xxx');, I was able to trace down the failure point. The problem in my case was that I had placed the cocos2d library in a common location. This worked great for prototyping and general development, but failed when I packaged the webworks app and '../Cocos2d' was not available. The solution was to alter the engineDir property in cocos2d.js to point to the new location of the cocos2d library.

 

Final Notes

When working with Cocos2d-x, it is important to keep in mind how it works. This will let you effectively place breakpoints or alert statements at key points to let you know when logic is being executed. While I was able to get my app working it would be great to have more options to debug on app startup. :)

Cocos2d-x does not require the webworks.js file to run as long as you are not accessing any device-specific functionality. I tried going down that path and found it overly-complicated my code without adding any benefit.

Addendum: Cocos2d-x HTML5 and plist / png files

One thing I ran across while generally debugging my cocos2d app was this error:

Uncaught cocos2d:Not a plist file CCSAXParser.js:60
cc.SAXParser.cc.Class.extend.parseCCSAXParser.js:60
cc.DictMaker.cc.Class.extend.dictionaryWithContentsOfFileCCFileUtils.js:372
cc.FileUtils.cc.Class.extend.dictionaryWithContentsOfFileThreadSafeCCFileUtils.js:315
cc.SpriteFrameCache.cc.Class.extend.addSpriteFramesCCSpriteFrameCache.js:190

 

If you run across this, make sure that you preload your spritesheet in the main.js file. Also ensure that both png/plist files are in the same directory with the same root name (like mySprites.png and mySprites.plist).