How To Use The CocoonJS Developer App

Gaining Valuable Test Feedback Without Leaving Your Game

What It Is

The CocoonJS Developer app is a wonderful tool for testing HTML5 mobile games. It allows you to run your game on a mobile device as well as have access to the js console right from within your game. Any logs you write from your game will be visible from the developer app menu which sits on top of your game. Log types each have their own dedicated tab (error, info, etc) but there is also an "all" tab if you want just one view of everything. There are additional helpful tools as well, like the ability to restart your game on the fly and an fps counter overlay.

How It's Different

This part is important. If there's any one thing to get from this article, this is it.

The CocoonJS developer app does not work the same way as the normal compiled CocoonJS app.

For a normal app, you simply drop in a zip file of your root game folder (where index.html lives) and CocoonJS kicks back out a compiled app file ready to go. (.apk or .ipa) The developer app starts off the same way but actually working with what it kicks out is quite different. (this is where most people get lost!)

Important Note

As of the writing of this article, the compilation of an iOS developer app is broken. The Cocoon compiler will work for Android but will fail creating the iOS developer app. From what I understand, it has been broken like this for some months now. Hopefully it will be fixed in the near future!

How To Use It

I'm going to list each step in order that you'll need to follow to work with the developer app. (plus a tip after that to help you save time later on)

This is all assuming you already have a project setup within CocoonJS. It is a straightforward process so if you haven't done that yet, go ahead and take care of that first.

  1. Upload the zipped up root folder of your game just like you would for a normal CocoonJS compilation.
  2. When Cocoon is finished compiling it, download the generated zip file, extract it, and install it on your phone like you would with any side loaded app.
    • Take note, later versions of Android won't allow apk installation from just anywhere. The Google drive account associated with the Google account on your phone will work, though. If you get a cryptic installation error message, try uploading the apk to your Google Drive account and then installing it directly from there through the Google Drive app.
    • This is where things are quite different! If you fire up the app you will see...a file manager? What is this?
  3. Remember that zip file you uploaded earlier to Cocoon? Grab that again and transfer it to your phone. (Google Drive, etc)
  4. Now you can open up the developer app that you installed. You can enter a url to the zipped root folder of your game as one option of loading it up. I preferred to transfer the zipped file to my phone and load it locally but to each their own.
    • Regardless of how you load your zip file from within the developer app, I recommend you "favorite" it. The app has a glitchy way of sometimes not displaying your file system properly. So, when you have navigated to your zip file from within the developer app, before you tap on it, first hit the menu button and choose the option to select multiple files. Then, select your zip file and tap on the icon towards the bottom that looks like a heart with a little "+" on it.
    • This will add that specific location and filename to the 3rd tab (favorites) and as long as you always name your zip file the same thing and store it in the same place, you can easily fire it up from the favorites tab without having to track it down again through the janky developer app file manager. Good stuff!
  5. You're almost there! You've transferred your zipped root game folder to your phone. You've opened up the Cocoon developer app that you created earlier. From within the developer app, you've navigated through it's file manager to your zipped game folder. Now, just tap on the zipped folder and you will see 3 webview options appear towards the bottom of the screen. Tap on the one that you want and away you go! (always Canvas+ for me but I'll talk about that in another article)

Final Tips

Whew! It seems like a bit of an ordeal at first but once you do it a couple times, it's quite easy to load up test builds of your game and gain valuable feedback from within the developer app. Being able to log out information and try/catch errors is a very helpful way to quickly debug your game directly on a phone.

Another reason this is extremely helpful is for testing Cordova plugins. Since Cordova plugins are tough to test from a computer, you can easily find yourself feeling like you have to completely compile an app every time you want to see if you've implemented something correctly. Here is the beauty of the developer app.

You (usually) only have to compile it once!

That's right. Even if your code changes, if you just load up your new zipped game folder from within the developer app that you initially made, it will load your latest code just fine! The only time you'll want to recompile the developer app is if you have added new Cordova plugins. As long as you haven't done that, though, just transfer over your latest zipped game folder, and test away!

Hopefully this will help you get up and running quickly with the Cocoon developer app. It can be a great tool but is also very frustrating to use since the docs are kind of lacking. Once you have the hang of it, though, it will likely become an integral part of your development process. Happy coding!


Subscribe for new game announcements!

Email privacy guaranteed. Emails will be rare and will never be spam.