It was along the lines of:

• if(key[right arrow]) speedx += 10;
• sprite.posx += speedx;

Sometimes I miss the old days… The new path from input to action now looks like:

• set up key bindings from default or configuration data
• for each human player, translate input into commands based on bindings table; “right arrow” becomes “move right”
• send commands to each player’s controlled entity
• each entity processes commands through its state machine(s); if we’re on the ground, “move right” becomes “run right”
• active states run actions – in this case, the “run right” state applies horizontal force to the entity’s physical body
• the graphical representation of the physical body is updated

The new process is certainly more powerful, but requires somewhere around 1000x more effort to write. Below lies the implementation of the above process, the control tech demo. You can use the arrows to control all the various entities, and [square backets] or the mouse to switch entities. Your entity’s active state machines are displayed in the debug line at the bottom.

One of the nice things about this newfangled control system is that it meshes very well with the AI, which only needs to supply a command list to an entity, and not worry about the implementation details. You can see this in action when you launch a guided missile – it will follow the mouse cursor using a generic AI “chase” algorithm. This release also incorporates various other enhancements, including the launcher from a previous post.

Jetpack 2 Engine Status

I meant to have this demo out a month ago, but I opened up the Pandora’s Box of AS3 code optimization and fell in. This had to be done at some point, so I’m glad its mostly out of the way. On the plus side, I found several optimizations that doubled the frame rate of the game engine – there will be a big post on this later. The engine is pretty close to basic playability now, and I’ll be releasing a special retro version of Jetpack in March.

Personal Stuff

My gallbladder surgery was successful, but I’m only feeling about 25% better. I think it was worth it, but it looks like that wasn’t the cure-all I was hoping for. Thanks to all the well-wishers!

I tried this with just an image: when it was clicked, it would hide itself and embed the SWF where the image had been. Unfortunately, the SWF was not focused and would have to be clicked again, and Firefox has a flaw that does not always allow javascript to focus a SWF . Therefore the nice and simple image idea had to give way to a whole separate SWF as a launcher for the examples. The launcher is always running, but it’s small and the frame rate is low and it doesn’t do too much. Once the launcher is clicked it loads the example SWF and bumps up the frame rate to the proper level.  Of course, since this is Actionscript, what takes a sentence to write took 2 days to implement.

This is a form of preloader, and I’ve gotten confused a few times when thinking about this, so I’ll document it here.  It also helped me to refer back to my post on preloaders.

preloader via separate swf

• displays “click to start” and waits – this can be bypassed via an argument to the swf
• loads the main swf while updating progress
• sets the new framerate, activates the main swf, and goes away

preloader embedded in main swf

• the preloader is on frame 1 of the timeline, and begins to execute while the rest of the timeline loads
• large assets are embedded in later frames
• the preloader passes control to the main program once the swf fully loads

For Jetpack, I’m going to attempt a combination of the 2 methods, so the user experience will be as follows:

• The game window will instantly show loading progress (preloader swf)
• The preloader will fade away, revealing a Jetpack level in demo playback (main swf preloader)
• While the demo game runs, a status bar will show progress as the rest of the assets (mp3 music) load
  (At this point, an in-game ad could be shown, but the income from those is not impressive and I’d rather not clutter up the game.)
• When loading is complete, the main menu will fade into view

There are some other advantages to using a launcher swf that I can think of:

• When users embed the launcher swf on their own websites, it will always load the latest version of Jetpack from JetpackHQ.
• I’ll have full stats on who is playing and where.
• Security against game reskinning is improved, by having the launcher and the main swf validate eachother.

Getting the launcher just right took some struggling with Actionscript, but the result works great.  It’s only 2k, and can serve just about any swf file (on the same server).  I was able to find a way to read the target framerate from the loaded swf and set that before launching it.  You can also read the width & height, but I know no way of resizing the SWF at runtime without using javascript.  I’ve attached the source code to this project at the bottom of this post.  Here’s a sample:

function Startup()
{
    // ARGS - launch='', now=0/1
    var args = stage.loaderInfo.parameters;
    if(args.launch!=undefined) launch_swf_path = args.launch;
    if(args.now!=undefined) wait_for_click = !int(args.now);
    if(!launch_swf_path) Fail("usage: launcher.swf?launch=abc.swf&now=0");

    if(wait_for_click)
    {
        Show_WaitForClick();
        stage.addEventListener(MouseEvent.CLICK, StartLaunch);
    }
    else StartLaunch();
}

//--------------------------------------

function Shutdown()
{
    root.Shutdown();
    root = null;
    System.gc();
}

//------------------------------------------------------------------------------

function StartLaunch(event:MouseEvent=null)
{
    if(wait_for_click)
    {
        stage.removeEventListener(MouseEvent.CLICK, StartLaunch);
        Hide_WaitForClick();
    }
    Show_Preloader();
    loader = new Loader();
    loader.contentLoaderInfo.addEventListener(Event.COMPLETE, CheckReady_Hack);
    stage.addEventListener(Event.ENTER_FRAME, CheckReady_Hack);
    loader.load(new URLRequest(launch_swf_path));
}

//--------------------------------------

function CheckReady_Hack(event:Event)
{
    // in certain cases when not waiting for click, complete/init fires but loaderInfo.frameRate
    // is not accessible.  misinformation from the official ActionScript docs: "When the loaderInfo
    // object dispatches the init event, you can access all properties of the loaderInfo object"
    if(event.type==Event.COMPLETE)
    {
        ready_hack = true;
        loader.contentLoaderInfo.removeEventListener(Event.COMPLETE, CheckReady_Hack);
    }
    if(event.type==Event.ENTER_FRAME)
    {
        if(!ready_hack) return;
        stage.removeEventListener(Event.ENTER_FRAME, CheckReady_Hack);
        Launch();
    }
}

//--------------------------------------

function Launch()
{
    Hide_Preloader();

    var swf:DisplayObject = loader.content;
    // frameRate, width, height are only available before unload()
    stage.frameRate = swf.loaderInfo.frameRate;
    loader.unload();
    loader = null;

    // clear the stage
    while(stage.numChildren) stage.removeChildAt(0);
    // launch the loaded swf
    stage.addChild(swf);
    Shutdown();
}

Download launcher-2009-11-17.zip

There are very few good large scale games written for Flash, and there’s a good reason why: Actionscript is chock full of undocumented problems that Adobe is either unaware of or unwilling to fix.  I feel bad for anyone who was introduced to programming with this language.  I wish I had documented all the roadblocks I’ve had to work around, but I’ve only got a small sample of the most heinous or recent ones that are causing headaches.  I don’t have any saved up for part 2 of this series, but I’m confident that won’t be a problem.

Mysterious Arrow & Numeric Key Issue

Recently, on one of my computers, arrow and number keys are firing key-up immediately after key-down, so you can’t tell if one of the keys is held down.  Many flash games never catch the key-down event at all, so most flash games are unplayable for me on this computer.  I have no idea why – I’ve tried several recent versions of the Flash player and both the debug/release versions, both in-browser and standalone.

Mysterious Faint Box

On another one of my computers, whenever an object is rotated a very faint solid rectangle appears behind it.

The Registration Point Problem

Most graphical objects in Actionscript have a registration point (or “center”) at the object’s center, meaning when you set an object’s position you are saying where the center of the object should be.  This also means that rotation occurs more or less as you would expect.  Bitmaps don’t work this way – the registration point is the top left of the object.  There is no way to move the registration point.  What you have to do – and all this is completely undocumented – is hack a solution by applying an offset via matrix transformation, and never again using the object’s x, y, or rotation properties.  There are many many people asking about this problem on the web, and only a few partial solutions are out there.  I wasted an entire day and pulled out a lot of hair figuring this out.

Alpha / ColorTransform is slow

If you change the opacity of your visuals, you’ll notice a significant drop in performance.  I was suprised by this, because I’m also importing graphics with an alpha channel, and those don’t have the slowdown.  I’m guessing that Flash’s drawing algorithm must be applying the alpha as a separate step before the blit, rather than doing it during the blit.  To get around this and other suboptimal behavior, I’ve written a system to automatically cache a graphic after all the effects are applied, and mark the cache dirty when an effect changes.  Also, when opacity is set to zero the processing continues unabated – you need to manually set the graphic’s visibility off when this happens.

More Reading

There used to be some other websites with more Actionscript issues, but they seem to be gone.  If you find any more, please share them.

Iconara’s Architectural Atrocities
Choice quote:

The ActionScript 3.0 API:s have a few interfaces, in general it’s a good thing, it shows that the Macromedia/Adobe developers actually understand something, which hasn’t been obvious in the past.
The decision to include interfaces in AS2 was probably a manager or marketing executive saying “hey, all the other languages have something called ‘interfaces’, why don’t we?”, and the developers quietly obeyed.

I evaluated Kindisoft’s secureSWF, Amayeta’s SWF Encrypt, Ambiera’s irrFuscator, and LockLizard’s Lizard Flashguard.  Based on the level of security features, ease of use, and stability, the tool I’ve chosen for this task is secureSWF.  It offers several good features, and the ones I found most useful are:

• renames identifiers
• uses several techniques to obscure code flow
• encrypts strings
• optimizes code
• has build process integration

Obfuscating Actionscript is a pretty complex task and secureSWF handles it well – my SWF ran perfectly with adjustments to all security settings.  Here are the results of my rough performance comparisons:

no security
plain SWF: 211k , 37fps

default settings
secure SWF: 293k, 35fps
40% larger, 6% slower

custom settings – disabled “control flow obfuscation”
secure SWF: 244k, 37fps
15% larger, no performance loss

Tweaking the settings for less aggressive encryption can give better size and performance, but I consider the small performance hit to be a mandatory cost of business for creating a mid-scale game using Actionscript.  If you have a lot of high quality original source code that you want protected, I highly recommend Kindisoft’s secureSWF.

What’s Done

• input handler: command bindings > state machine > entity (command stream input for the state machine could eventually be: an AI, a network player, or demo playback)
• world cycle: graphics & basic physics – auto adapting frame rate independent from game tick, client-render-prediction-capable
• animation system: vector & bitmap, automatic cacheing, adapts to frame rate
• original map import: to faux-3d tiles, layered parallax rendering
• basic gui & menu system
• asset loading & management system
• flash platform: source encryption system, security wrapper, preloader
• website: improved template/page module system, nice request routing system, smooth deploy system

What’s New

Physics Engine

I’m tinkering with the Box2d physics engine for ActionScript 3, and I’m very impressed with its power and flexibility. It has many more features than I need, and I’m just hoping it turns out to be fast enough on slow computers. We’ll be able to have much more realistic effects without any extra work as long as this library turns out to be fast enough. I’ll be releasing a demo soon.

Refactoring (warning, serious programmer-speak ahead)

In the last couple weeks, I’ve refactored a good chunk of the code to accomodate some ideas I’ve been exposed to – the benefits of dependency injection and service locators.  These  two patterns may seem to be at odds, but I think each has benefits in different circumstances.  By focusing on using DI as much as possible without major inconvenience, I have increased the logic and readability of my code.  By falling back on a service locator to avoid bending over backwards to be 100% DI, I’ve kept the code clear and the configuration centralized.  The result is, the code is a lot better organized and easier to work with.

I’ve also decided to abstract the platform.  Initially I didn’t bother, since Actionscript is so intertwined with Flash/Flex, and I’m only targeting one platform, but I think abstraction is worth it for two reasons: logical code separation and future portability.  The basics like Math functions I’m leaving in place, but I’m wrapping input devices, graphical objects, and certain platform-specific functionality like event handling.  It makes the code a lot clearer to have most of the obscure Flash specifics in one place, and it will be that much easier to port the code if it’s ever needed.  Also, it brings a great feeling of inner peace to look at code and not see a single reference to MovieClip.

A preloader gives the user something to look at while the rest of your program loads. This is one of the nice things about SWF’s, they are capable of streaming – showing part of their content before fully downloaded. The way you do this is by putting all the content to be loaded later on a later frame of the SWF timeline. This does get a little complicated, because ideally you should preload not just your data, but your code as well. Any classes you don’t need for the preloader should be placed on a later frame along with any library assets.

This is where a big bug in ActionScript 3 shows up – the “Export classes in frame” setting appears to be badly broken, as discussed on actionscript.org. As you can tell, Adobe’s error is making some professionals desperate to find a workaround. Well, thanks to others in the ActionScript community, I’ve finally discovered the workaround. Unfortunately it involves abandoning Flash in favor of Flex. But, this isn’t as bad as it may sound. While I detest the Eclipse-based Flex Builder IDE, I discovered a fantastic (and free) tool called FlashDevelop that is a superior development environment to Flex Builder or Flash, and offers easier customization while lacking just a little polish (for one thing, syntax highlighting must be edited via XML file). FlashDevelop uses the command-line SWF compiler mxmlc that comes in the new (also free) Flex 3 SDK.

Actually since Adobe has all these nebulous products floating around that all pretty much do the same thing (Flash, Flex, Air, who knows what else), it’s a little confusing what language you are using for your source files. It’s ActionScript but it’s the Flex brand of ActionScript, which is a few tweaks different from Flash ActionScript. They could just merge all these tweaks into a single language and let you choose which features you want to use, but I imagine like in many other things computer, there’s less money in making things simple. Anyway, basically in Flex-ActionScript, you can embed all your library assets via source code, rather than via an IDE. Although the way you do this is a little awkward, I find it highly preferable. And you can still use advanced layouts and components by just including them via SWC

Once you get your project converted to Flex, here is the fix: instead of monkeying around with the timeline, set your preloader as your primary build class, and use the command-line option “-frame” to put your main program on frame 2 (placing the line [Frame(extraClass="Main")] in your preloader appears to be equivalent). Thanks to Lars Gerckens for his research, and BIT-101 for this alternate solution. And of course thanks to Adobe for providing such horrendously incomplete documentation that things like this have to be discovered through much trial and error. I can’t fault them too much though, since they are at least finally strangling the abomination that was Macromedia’s ActionScript 2.

After your preloading is done, you have to start the main class – but you can’t reference it because then Flex will include it, and all the classes it uses, along with the preloader on frame 1. Here’s how you instantiate it without referencing it (‘Main’ is the name of the main class):


nextFrame(); // goto Main frame
var classdef:Class = getDefinitionByName("Main") as Class;
var main:DisplayObject = new classdef(); // runs itself


Now there’s another problem – your Main class won’t have a stage object until after you call addChild(main) – but how does Preloader tell Main to initialize after adding it, when Preloader doesn’t know what class Main is? The way I do it is by storing the stage in a global variable, then letting main add itself to the stage in the constructor. I use a class called Config that contains static variables for build type, debug mode, stage, and a few other globals. Generally globals are a bad thing, but in certain cases like this the time they save is worth it.

If you find any caveats or improvements, let me know!

=======================

One problem still exists: when loading this in a web browser, loaderInfo.bytesLoaded seems to only reflect the first frame. We need to know the total bytes for the entire SWF to accurately show load progress. From looking at the source code to mx.preloaders.DownloadProgressBar, Adobe’s own code actually has to guess at the size of the SWF it’s loading. Weak. So no “percentage loaded” indicator is going to be accurate unless you explicitly provide it with the estimated size of your SWF.

This is why I haven’t released any flash demos yet, I’m trying to find a resolution to this problem before releasing a simple demo that contains my entire source code. There are tools out there to encrypt ActionScript, but none of them work with ActionScript 3 yet – and from what I understand, a separate tool is needed to obscure variable names, a feature that is very important to protecting code.

Maybe this issue is why there are very few large games created for Flash? Still, I intend to continue on this path, at least for this game.