HTML5 AppCache and Keeping Clients Updated

If you've played Entanglement or Thwack!!, you may notice that it takes a while to load the first time. Fortunately, if you've installed Entanglement as a web app, or played Thwack!! more than once, you may have also noticed that subsequent visits require much less time to load. This is thanks to the HTML5 application cache.

The application cache (or "appcache" for short) allows us to store the game and all of its audio and graphics files locally on your computer (here's a nice tutorial on implementing an appcache). Next time you play the game, the application cache loads the files from your computer rather than pull them from the Internet. The beauty of this is two-fold. First, the game can start loading quickly since it doesn't need to check for anything online first. Second, the game can load without a connection to the Internet at all!

One drawback to this is that if someone plays the game and then returns some time later, the next time they play the game their browser loads a version of the game that's potentially weeks or even months old. If there's an updated version, appcache will load the files in the background to prepare for the next time the game is loaded, but the version the player is currently experiencing is the old version until they reload the page. This isn't too much of a problem with Entanglement where changes from one version of Entanglement to another do not negatively effect the experience.

What a player sees if running an old version

However, with the online multiplayer aspect of Thwack!! it's a bit more disruptive. With Thwack!!, each client independently calculates the results of a given turn, and those results have to match up with each other. For instance (not connected to reality... ...okay maybe a little), if Todd decides on a whim to change all of the discs' sizes, weights, and damping, the new version he deploys will calculate a different result for a turn than an older version stored in appcache. This effectively breaks the experience for not only the player whose browser loaded an old version of Thwack!! but also all of the players connected to that particular game.

The fix is fortunately quite simple. When a new version has loaded in the background, we know that we're not running the latest version. We can check this by implementing the following event listener:

var newVersionWaiting = false;
var updateReady = function()
{
    newVersionWaiting = true;
};

window.applicationCache.addEventListener('updateready', updateReady, false);

Now that we're aware of a new version waiting on the sideline, we can notify the player that they're running an outdated version before we let them in on a multiplayer game. Additionally, we attach a page refresh call to the message dialog's "OK" button to make it even easier for them to get the most updated version. Here's a snippet from Thwack!! where "messageBox" creates the dialog you see in the screenshot above. The first parameter is the message and second parameter, a function, is executed by clicking "OK":

if(newVersionWaiting)
{
    messageBox(RELOAD_THWACK, function(){window.location.reload();});
}