PhoneGap Legends – A Sample Game App

Next week I’ll be representing Adobe at GDC 2013, and demonstrating how Adobe Creative CloudPhoneGap, and PhoneGap Build can be great tools for building casual gaming experiences. In preparation, I’ve been working on a gaming sample application that shows off the potential of HTML games packaged with PhoneGap.

…and now I’d like to introduce you to PhoneGap Legends. PhoneGap Legends is a fantasy/RPG themed demo that leverages HTML DOM animation techniques and targets webkit browsers. I was able to get some really outstanding performance out of this example, so be sure to check out the video and read the details below. The name “PhoneGap Legends” doesn’t mean anything; I just thought it sounded videogame-ish and appropriately fitting.

PhoneGap Legends
PhoneGap Legends

This game demo is an infinitely-scrolling top-view RPG themed game that is implemented entirely in HTML, CSS, and JavaScript. There is a scrolling background, enemy characters, HUD overlays, and of course, our “protagonist” hero – all that’s missing is a story, and general game mechanics like interacting with sprites.

Again, I was able to get some *really outstanding performance* out of this sample, so I wanted to share, complete with source code, which you’ll find further in this post (and I encourage you to share it too). Take a look at the video below to see the game in action on a variety of devices. Every single bit of this is rendered completely with HTML, CSS, and JavaScript – there are no native portions of the application.

Update 3/24:  If you’d like to test this out on your own devices, you can now access it online at   However, it will still only work on webkit browsers (Chrome, Safari, Android, iOS, etc…), and is optimized for small-device screens.  If you attempt to use this on a very large screen, you’ll probably see some sprite clipping.

Disclaimer: This sample app is by no means a complete game or complete game engine. I’ve implemented some techniques for achieving great performance within a PhoneGap application with game-themed content, but it still needs additional game mechanics. I also wrote this code in about 2 days – it needs some additional cleanup/optimization before use in a real-world game.


Full source code for this demo application is available on GitHub. This code is provided as-is: I will be making a few updates over the next few days in preparation for GDC next week, but for the most part, it is stable.

Development Approach

The PhoneGap Legends application was built following the performance tips that I posted earlier this month. The game is built so that it uses a game loop based upon requestAnimationFrame to perform all UI updates. This gives it a scheduled interval that is in sequence with the browser’s redraw cycle.

In general, the DOM is as shallow as possible for achieving the desired experience. All “sprites”, or UI elements are basic DOM nodes with a fixed position and size.  All DOM elements have an absolute position at 0,0 and leverage translate3d for their x/y placement.  This is beneficial for 2 reasons: 1) It is hardware accelerated, and 2) there are very, very few reflow operations.  Since all the elements are statically positioned and of a fixed size, browser reflow operations are at an extreme minimum.

The background is made up a series of tiles that are repeated during the walk/movement sequence:

Sprite Sheet for Background Tiles

In the CSS styles, each tile is 256×256 square, with a background style that is defined for each “type” of tile:

    width: 256px;
    overflow: hidden;
    position: absolute;
    background-repeat: repeat;
.tile_0 {      background: url('../images/background_tiles.png');     background-position: 0px 0px;}
.tile_1 {      background: url('../images/background_tiles.png');     background-position: 256px 0px;}
.tile_2 {      background: url('../images/background_tiles.png');     background-position: 512px 0px;}
.tile_3 {      background: url('../images/background_tiles.png');     background-position: 0px 256px;}
.tile_4 {      background: url('../images/background_tiles.png');     background-position: 256px 256px;}

The content displayed within each of the “sprite” DOM elements is applied using sprite sheets and regular CSS background styles. Each sprite sheet contains multiple images, the background for a node is set in CSS, and the position for each image is set using the “background-position” css style.  For example, the walking animation for the hero character is applied just by changing the CSS style that is applied to the “hero” <div> element.

Sprite Sheet for Hero

There is a sequence of CSS styles that are used to define each state within the walking sequence:

.hero_0_0{ background: url('../images/rpg_sprite_walk.png'); background-position:0px 0px;}
.hero_0_1{ background: url('../images/rpg_sprite_walk.png'); background-position:0px 96px;}
.hero_0_2{ background: url('../images/rpg_sprite_walk.png'); background-position:0px 192px;}
.hero_0_3{ background: url('../images/rpg_sprite_walk.png'); background-position:0px 288px;}

This game demo extensively uses translate3d for hardware accelerated composition.  However, note that the 3d transforms are all applied to relatively small elements, and are not nested. All of the “textures” are well below the max texture size across all platforms (1024×1024), and since it uses sprite sheets and reusable CSS styles, there are relatively few images to load into memory or upload to the GPU.


The following Creative Commons assets were used in the creation of this sample app and the accompanying video:

Image – Grass Texture:
Image – Trees/Bushes:
Image – Main Character:
Image – Enemies:
Image – Compass Rose:

Font – Avalon Quest:
Note: I used a free/open licensed font that could be embedded in the app for offline usage. This font was converted to a web-font package that can be embedded in the PhoneGap application using

Audio – Monster:
Audio – Music:


Again, in case you missed it above, Full source code for this demo application is available on github. This code is provided as-is:

On-Device Debugging With PhoneGap & iOS 6

Want to debug your PhoneGap apps, complete with breakpoints, DOM & CSS inspection, profiling, and more?  This is all possible with the PhoneGap Emulator, which allows you to leverage Chrome’s Developer Tools inside of the desktop Chrome browser (covered in detail here).  However, did you also know that you can have a rich debugging/development experience in an app that is actually running on a device?

Since the release of iOS 6 last Summer, we’ve all had the ability to debug PhoneGap apps while they are running on external iOS devices, or inside of the iOS simulator. I’m surprised how often I hear that people are not aware of this feature. With iOS 6 you can use Safari’s developer Tools to connect to any HTML content on the device, either in the mobile Safari browser, or inside of a web view. PhoneGap apps fall into that second category, they are based upon iOS system web view.

You can check out a preview of remote debugging on iOS in the video below:

In order to take advantage of this, you’ll first have to enable the remote web inspector for Safari on iOS. Just follow the instructions for “Debugging Web Content on iOS” from Apple – be sure not to skip the “Enable Web Inspector on iOS” section, which is hidden by default.  You have to enable this in iOS Settings in order for the desktop Safari Browser to be able to connect to any web content on the mobile device.

Once enabled, you can lever the full capabilities of Safari’s Developer Tools, including DOM & CSS inspection and modification, JavaScript breakpoints, storage, resources, exceptions, console logging, and more…


Unfortunately, this is only available for PhoneGap on iOS devices at this time. Android enables remote debugging inside of the Chrome browser, however that isn’t enabled for PhoneGap apps *yet*.  Whenever Google enables Chrome for web views inside of apps, it’s on!

More On Creative Cloud Workflow

I put this post together to follow up a few points from my last post about Adobe Ideas & Adobe Creative Cloud. I promise, I’ll get back to some technical & development topics in my next post. I’m just having too much fun with this right now…

Here’s another composition that I put together using Adobe Ideas, following the same workflow in my previous post: I sketched this composition in Adobe Ideas, then leveraged Adobe Creative Cloud to continue the editing process on the desktop.

Video: Adobe Ideas Composition

Disclaimer: I am not an artist or illustrator.  I primarily focus on writing software… the art stuff is just for fun.

Now, I want to elaborate a bit more about the Creative Cloud workflow. Creative Cloud is not just a subscription to all of Adobe’s creative and Edge tools. It’s also not just a “hard drive in the sky” that synchronizes your creative assets across your devices. It is both of these, and much more.

We’ve already covered that Creative Cloud empowers the seamless creation of content across mobile and desktop devices. You can create content using the Adobe Touch apps, and pull that into the desktop tools for refinement. For example, let’s take the sketch that I created in the video above… If I want to isolate and extract individual assets, I can do that very easily using the desktop tools:

Isolating Layers in Adobe Illustrator
Isolating Layers in Adobe Illustrator

I can also pull these layers into Photoshop for further enhancement. In this case, color correction, and rearranging some content (oh look, more elephants!).

Editing in Adobe Photoshop
Editing in Adobe Photoshop

Now, let’s consider workflow beyond just creation of content. What about collaboration and feedback? Adobe Creative Cloud empowers collaborative experiences too. Everything from simple sharing, to comments/feedback, even having the ability to break down and view individual layers of PSD files. Check out the video below for some more detail:

Video: Adobe Creative Cloud Workflow

You can share any of your Creative Cloud assets by email or simple URLs, where that content and workflow can be consumed on any device, anywhere. Need feedback from your customers? Just send them a link to the composition work in progress, and they can leave comments whenever they want.

Sharing and Collaboration with Adobe Creative Cloud
Sharing and Collaboration with Adobe Creative Cloud

In fact, If you’re interested, you can check this composition out for yourself. Here are the assets that I used to create this composition, which I’ve shared publicly. Although, I disabled the ability to download the original files. You can toggle PSD layers, or leave comments (just be nice):

Interested yet? You can get started with Creative Cloud here, for either individuals or enterprises. Yeah, I’m a technical person, and even I am captivated by the power of this workflow.

Video: Adobe Edge Inspect

Here’s a quick video introduction I put together for Adobe Edge Inspect, a *free* tool that enables synchronized browsing and debugging of HTML content between desktop and mobile devices. It’s definitely worth checking out, if you aren’t using it already.

Adobe Edge Inspect enables synchronized browsing across desktop and mobile devices. By pairing your devices with Edge Inspect running on your desktop, any content you view in the desktop browser will be synched to all paired mobile devices.

Synchronized Browsing

Adobe Edge Inspect also enables remote inspection of content running on those mobile devices. This includes on-device debugging capabilities for both DOM & CSS inspection & modification, console logging, and more.

Remote Inpsection

Adobe Edge Inspect also makes it easy for you to track and document visual issues on the remote devices. With just one button click, you can capture screenshots from all connected devices, complete with information about each device (OS, device name, screen resolution, etc…).

Screen Captures

Did I mention Adobe Edge Inspect is also free? It’s part of the free tier of Adobe Creative Cloud.

Adobe Ideas & Creative Cloud Workflow

In this post I’m changing things up a bit… Rather than focusing just on developer-centric topics, I’ve decided to show a little more creative workflow using Adobe Ideas.  Adobe Ideas is an awesome sketching app for the iPad. You can sketch whatever you want, whenever you want. It is all saved as vector content that you can then pull into Adobe Illustrator to integrate into your desktop workflow using Adobe Creative Cloud. Take a look at the video below to see it in action:

Once you save your sketch, it automatically gets synched with your Creative Cloud account. You can then pull the composition directly into Illustrator and use it within other creative suite tools.

Here’s the output of the exact composition shown in that video:


You can export as raster (png, jpg, etc…) or vector (ai, svg, etc…) formats, so it can be a great tool for enabling you to hand-sketch high quality graphical assets for your creative workflow.

Helpful links for getting started: