It’s called the bleeding edge for a reason. In our hurry to target the latest and greatest features in the most up to date Flash Player version, we can find ourselves in a sticky situation where buggy, but “valid” Flash Players can create a less than enjoyable game playing experience. At best our games will not work, at worst, they will work only well enough to give someone an experience so craptistcally bad that they decide that not only does our game suck, but so does our development company, the website hosting our game, and anything ever that was related to Flash in any sort of way. Yikes. There are a few ways to make sure that the user is using a Flash Player version that jives with our game, and we’ll explore the most fool proof in today’s article.

Flash Player Version Woes

I could go into depth on some of the issues I’ve had with various buggy releases of the Flash Player, but I’ll spare you the gory details unless you really want to know. Minor version flash player releases will eventually break your game if you’re doing enough fun stuff. Even 9.0.115 versus 9.0.124 created game breaking inconsistencies on our most recent project. Some of the symptoms are that the game will work in one browser but not another, the game will not run as fast (in one particular case, abysmally slow - it was unplayable), or the game will randomly crash in code that is completely benevolent. In all these cases, work arounds are preferable, but, in all these cases, at least alerting the user that a potential issue could exist might have been enough to salvage the situation.

SWFObject

Perhaps the more experienced readers would have noted that a solution to this particular problem already exists in the form of SWFObject. You should be using SWFObject and it is the best first line of defense against this particular issue, but it is not a catch all. Flash is a web medium, and often times you have very little control over where your .swf file is being embedded. You need another line of defense to account for those situations where SWFObject isn’t going to save your tail.

The Version Validator

As it turns out, the Actionscript library gives us the tools necessary to detect the player version. If your code knows that you need at least a certain flash player version to play, you can alert the player to the problem, and give them an opportunity to upgrade. Optionally, you can give them the choice to ignore the alert and try the game anyway. Today’s post comes with code that does exactly that.

Sample Usage

Let’s not kid ourselves. This is about as unsexy as code gets. So let’s just make it as quick and as painless as possible. You probably want to do this after your preloader but before your title screen:

    var versionValidator : VersionValidator = new VersionValidator( 9, 0, 999 );
    addChild( versionValidator );
    versionValidator.addEventListener( VersionValidator.VALIDATED, handleVersionValidated );
    versionValidator.addEventListener( VersionValidator.OVERRIDDEN, handleVersionValidated );                           
    versionValidator.x = this.stage.stageWidth / 2 - versionValidator.width / 2;
    versionValidator.y = this.stage.stageHeight / 2 - versionValidator.height / 2;
    versionValidator.validate();

That’ll show the pop up if the user has any version less than 9.0.999. Fun stuff. You’re free to add backgrounds and logos and whatever else you want. The example code adds a shiny logo and a black background. The VersionValidator inherits from Sprite so you can treat it just like any other visual element (including adding filters or whatever).

VersionValidator fires two different types of events. VersionValidator.VALIDATED is fired if the user has at least the minimally required version number (specified in the VersionValidator constructor). If this is the case, nothing is drawn to the screen. The validator pop up is never shown to the user, and it will silently clean itself up. There is an optional second event you can listen for, which is the VersionValidator.OVERRIDEN event. If you define this event on the VersionValidator, then it will give the user an option to override the error, effectively ignoring the alert and deciding to proceed anyway. You can use a different code path to handle this occurrence, or hook it up to the same listener as the VALIDATED event (as per the example) depending on if you want to add additional information about symptoms they might experience, or if you want to disable certain features that you know won’t behave in older versions.

Here’s a screen shot of the VersionValidator in action:

Don’t like the wording? The best thing about open source code is you can tweak it to your heart’s content. Here’s the source for you to play with.