Actionscript 3 Hidden Gem: addFrameScript

So it’s no big secret any more that in Actionscript 3, the MovieClip class has a hidden method that enables developers to add frame scripts at runtime. However, with great power comes great responsability. It would help if this were documented in the Flash docs but it isn’t. If you don’t want your SWF files to crash when using this method you MUST ensure that the playhead is stopped before calling this method. I discovered this by experimenting with when, and what I could do with this method, and yes you can remove any frame scripts added at design-time or run-time (at least with the current version of Flash player). Actually, the playhead does not have to be stopped if you are setting a null frame script.

What I had to do to make using this method easier was to override and provide a few extra operations to MovieClip objects:

private var __playing : Boolean = true;

override public function play () : void
{
	if (this.__playing)
		return;

	this.__playing = true;
	super.play();
}

override public function gotoAndPlay (pFrame : Object, pScene : String = null) : void
{
	this.__playing = true;
	super.gotoAndPlay(pFrame, pScene);
}

override public function stop () : void
{
	this.__playing = false;
	super.stop();
}

override public function gotoAndStop (pFrame : Object, pScene : String = null) : void
{
	this.__playing = false;
	super.gotoAndStop(pFrame, pScene);
}

override public function addFrameScript (... pArgs : Array) : void
{
	if (pArgs.length != 2)
		return;

	var frame : int = int(pArgs[0]);
	var func : Function = pArgs[1] as Function;

	if (this.__playing && func != null)
	{
		var nextFrame : int = this.currentFrame + 1;
		this.stop();
		super.addFrameScript(frame, func);
		this.gotoAndPlay(nextFrame);
	}
	else
	{
		super.addFrameScript(frame, func);
	}
}

This works great and my SWF files don’t crash anymore. Also one quick note on the arguments for the method. The accepted arguments are:

addFrameScript( pFrameIndex : int, pActionFunc : Function );

Keep in mind that the frame index is not the same as the frame number, and you can pass a null function to remove a frame script. As noted above, if the function is null then the playhead does not have to be stopped.