Preloader to Game Transition with Stop Propagation

This will be a quick post on some gotcha’s to keep an eye out for when loading your ActionScript 3 game swf from a preloader swf. Nothing revolutionary here, back in mid-December, I had posted a blog on ActionScript 3’s Event Handling and the stopPropagation method and just the other day working on the code for a new game project, I ran into a situation where I should’ve used the method, didn’t, and ran into some issues.

Note: If you’re here looking for code on how to write a flash preloader, Lee Brimlow’s video tutorial on Preloading in AS3 gives a beautiful example. When I was originally learning how to code a preloader, that tutorial, and a couple of other tutorials around the net that escape my memory at the moment, were absolutely perfect.

So that we’re all on the same page, I’ll do the roll call. Game.swf is how I’ll refer to the file containing your actual game code. Preloader.swf will be the wrapping preloader file.

Running just Game.swf, it loads up a title screen with some text and instructions, the game splash screen. As per design, we wanted to keep it simple, no buttons, just a Left-Click when ready to begin the game. Once the user Left-Clicks, we jump right on into the action.

Enter Preloader.swf. To get something functional and working posted ( as a deadline was approaching for an Alpha build ) I tossed a standard component Button with “Begin Game” label text on the stage, disabled, so that when Game.swf was completely loaded, the button becomes enabled, user clicks button, and BAM… we should be heading to the beginning of Game.swf which, as I mentioned, was the title screen with text.

I believe it was somewhere around the second day after I wrapped Game.swf inside Preloader.swf when I received an email from Gwen, which went something like this ( with my incredibly loose paraphrasing ), “Yeah, so, what happened to the instruction screen? Can you bring it back so my Prof knows how to play the game?”

You know how it is… little things like “title screens” and “instructions” and “important details” get completely side-stepped sometimes and you don’t even realize it because you’ve been working on some other way more interesting area than just “important details.”

As soon as I got the email, my brains went exactly to that last stopPropagating blog post, and the palm went to the face. Let’s take a closer look at the function in Preloader.swf that gets called once we click the “Begin Game” button.

* * wrong code * *
 


/** PRELOADER.SWF CODE **/
// Incoming MouseEvent from the "Begin Game" button
private function onBeginGameHandler( e:MouseEvent ):void
{
   // Percent displays the % Complete text
   removeChild( percentTxt );

   percentTxt = null;

   beginBtn.removeEventListener(
                                                      MouseEvent.MOUSE_DOWN ,
                                                      onBeginGameHandler
                                                   );

   removeChild ( beginBtn );

   // gameLoader is the content Loader Object that gets added to the stage
   addChild( gameLoader );

}

/** GAME.SWF CONSTRUCTOR CODE **/
public function Game()
{
   // code to display game title with event listener for MOUSE_DOWN
}

(not shown in code)
Preloader.swf loads the full Game.swf file showing % complete in a text box.  When complete, Preloader.swf’s “Begin Game” button listens for a MOUSE_DOWN event. Once clicked…

(previous code)
…the previous function runs,

  • adding Game.swf ( the content of gameLoader ) to the stage
  • Game.swf calls constructor displaying the title/instruction screen, also listening for a MOUSE_DOWN event

As that MOUSE_DOWN event comes bubbling back up from the depths, Game.swf’s title screen gets added on the surface, and automatically gets triggered from the previous MOUSE_DOWN event.  Looking back it seems obvious.  

At the time I didn’t even think about it as “well, they’re two separate swfs.”  However, those two separate swf’s are being added to the same (only) stage thus stacking them one on top of the other in the Display List… thus stacking them in the Events list.  

This is a quick grid I usually draw out if I’m ever not 100% sure whats going on with the display list and event handling.

roadmap sketch 

The best way I’ve found to handle the transition is the following:

* * correct * *
  


/** PRELOADER.SWF CODE **/
// Incoming MouseEvent from the "Begin Game" button
private function onBeginGameHandler( e:MouseEvent ):void
{

   //  Important!  This stops the MOUSE_DOWN event
   //  from traveling anywhere else.  
   <span style="color: #008000;"><strong>e.stopPropagation();</strong></span>

   // Percent displays the % Complete text
   removeChild( percentTxt );

   percentTxt = null;

   beginBtn.removeEventListener(
                                                      MouseEvent.MOUSE_DOWN ,
                                                      onBeginGameHandler
                                                   );

   removeChild ( beginBtn );

   // gameLoader is the content Loader Object that gets added to the stage
   addChild( gameLoader );

}

/** GAME.SWF CONSTRUCTOR CODE **/
public function Game()
{
   addEventListener( Event.ADDED_TO_STAGE , startMain );
}

private function startMain( e:Event ):void
{
   // remove listener for incoming event 
   removeEventListener( Event.ADDED_TO_STAGE , startMain );
   
   // code to display game title with event listener for MOUSE_DOWN
} 

Spelling the code out as simply as possible using the previous code,

  • use Begin Game’s MOUSE_DOWN Event to jump us to onBeginGameHandler()
  • @line 8: stopPropagation “erases” the incoming event, it did it’s job, it can leave now
  • @line 30: in Game constructor function, start listening for when Game is actually added to the stage, which will propel us forward in the code to startMain()
  • startMain() actually adds the Title/Instruction screen and it’s own event listener for another MOUSE_DOWN event

 

This handles all of our events, keeps us from adding excessive events or buttons, and follows the natural path that Flash will be heading down as it compiles.

That’s that.  I hope that tiny bit of logic is useful.

 

 

Extra DVD Commentary:
So I’m currently collaborating with Gwen Murray, a game designer currently in her Senior year at SCAD. As this is the first time working with an actual designer, and not just fumbling my way through torn napkins with notes and spending every 45 minutes back and forth between Photoshop and Flash, I have to say… man do I love having someone else make things pretty.

We’ve all got our strengths, and while I’m handy with Photoshop, that’s not my passion nor focus so it seems more a time-wasting means to an end as I get side-tracked playing around in Photoshop instead of being productive. It’s a beautiful thing indeed when you match the people that love making things pretty with the people that love making the 1’s and 0’s ‘do stuff.’

FacebookTwitterGoogle+Share

Leave a Comment

Your email address will not be published.