Of Document Classes and Timeline Code

My coworker Ezra and I just got through figuring out a bizarre bug in an application created with Flash CS3 (using ActionScript 3.0). Since I didn't see anything else about it online, I thought I'd post it here.

The Set-Up: A loader SWF loads in section SWFs. The section SWFs have timeline code that trigger events based on timeline animations.

The Problem: On their own, the section SWFs worked fine. But once loaded into the loader SWF, only their class code would execute; none of the timeline code would execute, not even traces.

The Really Strange Wrinkle: I created a minimal proof-of-concept test, and it worked fine. It even worked when I used the section SWF from the actual project. So the problem seemed to be in the loader (but it really wasn't).

Here's the code from the minimal proof-of-concept test. Here's the loader class:

package timelinetest {
 import flash.display.Loader;
 import flash.display.LoaderInfo;
 import flash.display.Sprite;
 import flash.errors.IOError;
 import flash.events.ErrorEvent;
 import flash.events.Event;
 import flash.events.IOErrorEvent;
 import flash.events.SecurityErrorEvent;
 import flash.net.URLRequest;
 public class TestLoader extends Sprite {
  public function TestLoader() {
   super();
   addEventListener(Event.ADDED_TO_STAGE, loadContent);
  }
  private function loadContent(event:Event):void {
   var loader:Loader = new Loader();
   var info:LoaderInfo = loader.contentLoaderInfo;
   info.addEventListener(IOErrorEvent.IO_ERROR, onContentIOError);
   info.addEventListener(SecurityErrorEvent.SECURITY_ERROR, onContentSecurityError);
   info.addEventListener(Event.INIT, onContentInit);
   loader.load(new URLRequest("./loaded.swf"));
  }
  private function onContentInit(event:Event):void {
   var info:LoaderInfo = event.target as LoaderInfo;
   addChild(info.content);
  }
  private function onContentIOError(event:IOErrorEvent):void {
   throw new IOError(event.text);
  }
  private function onContentSecurityError(event:SecurityErrorEvent):void {
   throw new SecurityError(event.text);
  }
 }
}

... and here's the section class:

package timelinetest {
 import flash.display.MovieClip;
 import flash.events.Event;
 public class TestLoaded extends MovieClip {
  public function TestLoaded() {
   super();
   stop();
   addEventListener(Event.ADDED_TO_STAGE, onAddedToStage);
  }
  private function onAddedToStage(event:Event):void {
   play();
  }
  public function onSpecialFrameReached():void {
   trace("special frame reached");
   stop();
  }
 }
}

... and on frame 10 of the root timeline in loaded.swf I had this code:

trace("calling onSpecialFrameReached()");
onSpecialFrameReached();

So on frame 10, it called onSpecialFrameReached(), which stopped playback. This worked fine. But similar code did not work fine in the actual project.

So What Was the Discrepancy?: Making the following modifications (underlined) to TestLoader.as caused the timeline code failure:

package timelinetest {
 import flash.display.Loader;
 import flash.display.LoaderInfo;
 import flash.display.Sprite;
 import flash.errors.IOError;
 import flash.events.ErrorEvent;
 import flash.events.Event;
 import flash.events.IOErrorEvent;
 import flash.events.SecurityErrorEvent;
 import flash.net.URLRequest;
 public class TestLoader extends Sprite {
  private var loaded:TestLoaded;
  public function TestLoader() {
   super();
   addEventListener(Event.ADDED_TO_STAGE, loadContent);
  }
  private function loadContent(event:Event):void {
   var loader:Loader = new Loader();
   var info:LoaderInfo = loader.contentLoaderInfo;
   info.addEventListener(IOErrorEvent.IO_ERROR, onContentIOError);
   info.addEventListener(SecurityErrorEvent.SECURITY_ERROR, onContentSecurityError);
   info.addEventListener(Event.INIT, onContentInit);
   loader.load(new URLRequest("./loaded.swf"));
  }
  private function onContentInit(event:Event):void {
   var info:LoaderInfo = event.target as LoaderInfo;
   loaded = info.content as TestLoaded;
   addChild(loaded);
  }
  private function onContentIOError(event:IOErrorEvent):void {
   throw new IOError(event.text);
  }
  private function onContentSecurityError(event:SecurityErrorEvent):void {
   throw new SecurityError(event.text);
  }
 }
}

See the difference? Before, there was no reference to TestLoaded in loader.swf. With this change, there is. Before, when loaded.swf was loaded, it contained the only reference to TestLoaded. This was as the document class, which had extra code from the timeline, so it was sort of a unique version of the class. But after the change, loader.swf had a copy of the TestLoaded class as well, a copy which had precedence over the unique version loaded in from loaded.swf. So the version with timeline code was ignored—no execution of timeline code.

The Remedy: This is something that was going to be done anyway—none of the loaded section SWFs should use the base version of the section/loaded class. They should all use their own subclasses. That way, nothing in loader.swf can block them.

Another solution (which isn't appropriate for our project, but it might be for others) would be to reference sections in loader.swf using an interface. (But even with this you'd still have to have different implementations in different SWFs, or they might conflict with each other—I think—should test that sometime.)

Really, though, there should be an option when assigning document classes, as there is when linking to a class from the library. You should be allowed to specify whether you want to use the class itself or an ad hoc subclass. If the former, the presence of timeline code should flag a warning message. Remind me to report this to Adobe.