So this year I’m doing my first Ludum Dare game competition. I’m very excited and have been trying to get my system ready to go before the theme is announced at 18:00 Pacific time. I’m running down my pre-flight checklist now.

My loadout:

Note the inspirational collages and ferret poster

(note: I’d love to put a link to every single one of these but that’ll take a long time and you can google them yourself.)

Software:

• FlashBuilder
• Text Mate
• Adobe Creative Suite
• bfxr
• Garage Band
• Amadeus Pro
• Art Rage

Libraries (probably won’t use all of these but they’re in there just in case):

• FlashPunk
• KitchenSync
• Abstract AS3
• AS3 Signals
• AS3 Utils
• AS3 Core Lib
• AS3 Data Structures
• Google Analytics
• Sterling
• zOMGamezLib (This is an old game engine that probably doesn’t even compile but I might pull some useful stuff from it. source)

You can follow me here or on Twitter @mimshwright

What followed was the discovery/invention of just such a thing, a nested, super-verbose function. The function achieves this by returning an instance of an internal class with nothing in it except for the next step in the chain.

package
{
	public class Bind
	{
		public static function updateProperty(object:Object, property:String):BindSource {
			return new BindSource(object, property);
		}
	}
}
import mx.binding.utils.BindingUtils;
class BindSource {

	private var targetObject:Object;
	private var targetProperty:String;

	public function BindSource(targetObject:Object, targetProperty:String):void {
		this.targetObject = targetObject;
		this.targetProperty = targetProperty;
	} 

	public function whenSourcePropertyChanges(object:Object, property:String):void {
		BindingUtils.bindProperty(targetObject, targetProperty, object, property);
	}
}

To call this function you would use:

Bind.updateProperty(foo, "bar").whenSourcePropertyChanges(baz, "bar");

Kinda cool! I soon realized that this technique has some characteristics that Objective-C messages don’t have. For example, each step can use more than one parameter (plus they each get their own code hinting). You can also provide multiple choices for what to do next providing a sort of branching behavior.

AngleFinder.getAngleOfVector(4, 4).inDegrees() 	// 45°
AngleFinder.getAngleOfVector(4, 4).inRadians() 	// π/4

You can even do free-form stacking of functions like this.

new Calculator	(5)                    // 5
                        .plus(3)            // 8
                        .times(2)          // 16
                        .dividedBy(4)   // 4
                        .minus(1)         // 3
                        .plus(2)            // 5
                        .equals();

I proudly named these “Matryoshka Functions” after the Russian stacking dolls even though I’m sure I’m not the first to try something like this. As it turns out, they’re about 10% practical and 90% clever hack. Even though there could be some potential use for this (especially with complicated, repetitive tasks), this technique conflicts too much with the way we normally code in ActionScript. Still, I thought it was cool enough to share with everyone.

Pros:

• Very descriptive
• Branching and stacking effect is interesting and potentially useful
• Code hinting shows the next step in the function as well as the parameter names
• Looks cool!

Cons:

• Abominable code style. Too weird to be useful.
• Difficult to know when to stop calling functions
• Not completing the function will produce unexpected results with no compile-time errors
• Each step requires you to pass the parameters from the previous step

Can you find any use of these? Can you think of a more efficient way to write the functions? Any other thoughts?

Check out the source with multiple examples (FlashBuilder project).
MatroshkaFunctionDemo

Interfaces are amazing things. When I was young and green, I didn’t understand their purpose, but after working with them for a while, I will defend their use to the end. I try to create lots of interfaces early on in my projects and I find that by keeping things flexible, it saves more time despite the extra typing, pardon the double entendre.

But this is not an article about why interfaces are so great. No, this is an article about the mysterious gap in the Flash Player API with regards to an interface for DisplayObjects. If you have a class typed as something like IView, there’s no way to enure that IView can be a parameter of display list functions like addChild().

Why can’t we guarantee that something is a DisplayObject through interfaces? There is a practical answer. The inner workings of the Flash Player are slowing unfolding to us with each version. We now have low level access to sound, byte streams, and text rendering. However, the display list still relies exclusively on one of the only truly abstract classes in ActionScript 3.0, the DisplayObject. Because a low-level drawing engine is not exposed to AS3 programmers, we don’t know how it works and we cannot guarantee through an interface that an arbitrary class can be drawn.

Fortunately, there are some workarounds that can help, each with their own strengths and weaknesses. Personally, I think #2 is the way to go. It’s practically dripping with polymorphic goodness.

1. Make your interface inherit from IBitmapDrawable and IEventDispatcher

   DisplayObject is the only class that uses both of these two interfaces so by combining them in your interface, you can sort of be sure you’re working with a DisplayObject. Still, this is my least favorite solution

   Pros:

   • Uses interfaces exclusively.
   • Only a DisplayObject would implement both of these.

   Cons:

   • There’s nothing to stop you from using this to create a class that isn’t a DisplayObject and that could cause problems.
   • You would still have to type cast to DisplayObject to use this as an argument for addChild().

2. Create an interface that exposes a method to return the object as a DisplayObject

   My personal favorite solution. It not only solves the problem of guaranteeing that a class can go in the display list, it doesn’t even require that the class be a DisplayObject.

   Here’s an example of what this would look like. IDisplayObject.as

   Pros:

   • Flexible solution that conforms to good OOD principles.
   • Uses interfaces exclusively.
   • Easy to apply. You can usually implement it with a single line of code: return this;

   Cons:

   • Requires you to use asDisplayObject() every time you want to use the object as a DisplayObject.
   • Calling foo.asDisplayObject() would throw an exception if foo was null so additional checks may be necessary.

3. Use an abstract class that inherits from DisplayObject

   Not an ideal solution primarily because Flash doesn’t have true abstract classes (although there are workarounds) but still totally valid.

   Pros:

   • Guarantees that the object is a DisplayObject. No type casting required.
   • Abstract classes can be treated virtually the same as an interface for practical use.

   Cons:

   • No true abstract classes in Flash.
   • Not as flexible as an interface-based solution since it forces you to inherit from DisplayObject.

XML-Schema (.XSD extension) are documents used to describe the format of XML files. They are similar to DTD (Document type declaration) files but much more powerful.

While working on some XML documents for a Flash site, I stumbled across the XML-Schema editor for Eclipse. The editor shows the XSD as a graphical representation of the model that you’re editing that looks similar to a UML class diagram.

Here’s a great article on how it works.

Benefits of using XSD

As I said, XSD allows you to define the format of your XML document but with much more detail that DTD.

• XSD allows you to type your data (integers, strings, booleans) so that you can better predict what format the xml will be
• It allows the creation of custom types which gives it an object oriented aspect
• You can use all kinds of restrictions for what kind of content can appear within a tag including the number of elements, whether values are required or not, you can even use regular expressions to limit the acceptable values. This is very nice when you’re working with a 3rd party who is generating the XML data.
• Using an XSD file can allow you to automate the validation of an XML file’s format

Once you’ve created your XSD file, you can use the new XML document wizard to create an XML file that links to your schema file. The wizard will automatically populate the XML document with valid data! Furthermore, as you edit the XML file you will get warnings and errors if you go outside the formatting requirements defined in the XSD. For example, if you define a tag <description> as having a maximum length of 128, you will see a visual error if your tag contains more than 128 characters. It’s a great way to forsee problems as you write them.

I hope in the future to write some kind of tool to parse XML based on an XSD file in flash. Apparently, Adobe had created an undocumented Flex feature to validate XML against XSD. Via Misprintt

Installing the XML extensions

Unfortunately, the editor is not installed by default and nstalling software in Eclipse is not very intuitive. I’ve done my best to describe the process here but if you need further help, check this entry.

1. Open Eclipse or FlexBuilder
2. Go to Help>Software Updates… ( > Find and Install for Eclipse 3.3)
   
3. Make sure you have the Europa or Ganymede update sites in the list of update sites:

   Eclipse 3.4 users:
   http://download.eclipse.org/releases/ganymede/
   
   http://download.eclipse.org/releases/europa/site.xml

4. Select the XML and XSD extensions in this screenshot. In Eclipse 3.4 you can search for them, in 3.3 you will have to look through the packages for them manually.
5. Restart Eclipse after the install is complete

By the way, this tip may be common knowledge to Flash users. I use FlexBuilder almost exclusively these days but recently have had to dip back into the twisted world of the Flash IDE so please refrain from leaving any comments about how I shouldn’t use the timeline.

The Problem

Say you have several different buttons for a site that each look of behave slightly differently but all share the same underlying functionality. In this example, I’ll be using a crude set of video controls. I want each of these different controls to respond to rollovers by showing the label beneath the icon.

Each  control has different icons and text so they’re going to need to be kept in different symbols. One solution might be to try to cram all the icons into one master symbol and change between the different icon frames using code. But that’s sloppy and unnecessary. Another solution might be to create 4 different classes that each implement the functionality or each extend a class with common functionality. This is a much better solution, but requires you to create 4 AS files for what functionally is just 1 type. You cannot use the same class for multiple symbols in your library though. Fortunately, Flash offers another solution that may be a bit less intuitive.

The Solution

If you needed to create the same sort of control components purely using code (using Flex for example), your first step would likely be to create some sort of base class that implements the common functionality of the 4 controls. Here’s an example of a base class for these 4 controls.

package {

	import flash.text.*;
	import flash.display.*;
	import flash.events.*;

	public class AbstractVideoControl extends MovieClip {
		// you'll need to create this text field on the timeline
		// and set the instance name to "label"
		public var label:TextField;

		public function AbstractVideoControl() {
			label.visible = false;
			addEventListener(MouseEvent.MOUSE_OVER, onMouseOver);
			addEventListener(MouseEvent.MOUSE_OUT, onMouseOut);
		}

		protected function onMouseOver(event:MouseEvent):void {
			label.visible = true;
		}

		protected function onMouseOut(event:MouseEvent):void {
			label.visible = false;
		}
	}
}

Note: In many non-ActionScript languages, there is a construct called an “abstract type” which  is simply a base class that cannot be instantiated on its own, only extended. In Flash, proper abstract types don’t exist, but we can consider a class Abstract if it shouldn’t be instantiated without being subclassed. More on that at Wikipedia.

Next, let’s make our controls extend this class. For each symbol, check the Export for ActionScript box in the symbol properties. Since Flash can automatically generate classes for symbols when an .as file doesn’t exist, the only thing you’ll need to fill in is the Base Class field (later, you can create a class for PlayButton if you need one). Make sure you use the fully qualified name if you’re using packages.

Moar

I found this technique was very useful for when I wanted to animate TextFields on the timeline. Timeline animations, as you probably are aware, only work with MovieClip symbols. That means that even simple animations on text require the text to be contained in a symbol. I created an AbstractTextFieldWrapper class so that I could easily work with animated type without having to create new classes every time the format changes.

package {
	import flash.display.MovieClip;
	import flash.text.TextField;

	/**
	 * This class allows you to create an animated text field on the
	 * timeline and still set the text of the field without creating a new
	 * class for each text field that does this.
	 *
	 * @use In the flash library, create a new movieclip symbol containing the
	 * 		textField. Make sure you set the instance name for the text field to
	 * 		"textField". Make the base class for the symbol
	 * 		"AbstractTextFieldWrapper".
	 * 		In another class, use the type AbstractTextFieldWrapper insatead of
	 * 		TextField for your text field variable.
	 */
	public class AbstractTextFieldWrapper extends MovieClip
	{
		public var textField:TextField;
		public function set text(text:String):void {
			textField.text = text;
		}
		public function get text():String {
			return textField.text;
		}
	}
}

The Hard Limit approach

The first attempt I made at the N-gleton was to simply throw an error when the class had been instantiated too many times.

package {
	public class NGletonHardLimit {
		protected static var maxInstances:int = 3;
		protected static var numberOfInstances:int = 0;

		public function NGletonHardLimit() {
			if (numberOfInstances >= maxInstances) {
				throw new Error ("There can only be " + maxInstances + " instances of this class");
			}
			numberOfInstances++;

			// initialize code
		}
	}
}

This was shortly followed by a slightly more friendly version of the same idea…

package {
	public class NGletonRequestInstance {
		protected static var maxInstances:int = 3;
		protected static var numberOfInstances:int = 0;

		public static function requestInstance():NGletonRequestInstance {
			if (numberOfInstances >= maxInstances) {
				return null;
			} else {
				return new NGletonRequestInstance(new Key());
			}
		}

		public function NGletonRequestInstance(key:Key) {
			// initialize code
		}
	}
}
class Key {}

However, I soon realized that this method is quite flawed in its logic. The counter is actually just counting the number of times the requestInstance() method is being called rather than truly controlling the number of instances of the class. It also doesn’t allow you to release an instance and decrement the instance count. Perhaps something like this would work in C where you can use alloc and dealloc but for Flash, it doesn’t really make sense. Besides, It doesn’t really seem useful.

Cycling through instances

Next, I tried looping through the same limited set of instances. Each time you request an instance you get a new one until you’ve reached your limit, then it starts over with the first instance again.

	package
	{
		public class NGletonLoop
		{
			protected static var maxInstances:int = 3;
			protected static var numberOfInstances:int = 0;
			protected static var instances:Array = [];

			public function NGletonLoop(key:Key) {
				// initialize code
			}

			public static function requestInstance():NGletonLoop {
				var n:int = numberOfInstances++ % maxInstances;
				if (instances[n] == null) {
					instances[n] = new NGletonLoop(new Key());
				}
				return NGletonLoop(instances[n]);
			}
		}
	}
	class Key {}

This approach just felt wrong. In fact, it was totally stupid. There is no way to know what you’re going to get when you request an instance and it seems like it would be very easy to overwrite data without even knowing it. You still have the problem of the instantiation being counted rather than the actual objects. Besides, it’s really totally useless.

It was looking like the whole idea of an N-gleton may not really have a practical application. But in the name of theoretical computer science, I chose to press on and try one more idea I had.

Tracking individual instances

The previous idea of storing instances in an Array seemed to make some kind of sense to me but it was missing individual control over the instances. So I decided to try using an index to track the instances. I soon realized that a Dictionary that uses objects as keys might give a more useful identifier than an integer. The maximumInstances didn’t really make sense any more so I took it out. I seemed to be onto something but it wasn’t really the N-gleton I had imagined, it was something more useful. I called it an IndexedObject.

	package {
		import flash.utils.Dictionary;

		/**
		 * An example of a class that tracks multiple individual instances by using a dictionary.
		 */
		public class IndexedObject {

			/**
			 * Stores the actual instances of the class.
			 */
			protected static var _instances:Dictionary = new Dictionary(false);

			/**
			 * The identifier that the dictionary uses to reference this instance.
			 */
			public function get id():* { return _id; }
			protected function set id (id:*):void { _id = id; }
			protected var _id:*;  

			/**
			 * Gets an instance of the class. Similar to how a singleton would get the
			 * instance but uses an identifier token to specify which instance to get.
			 */
			public static function getInstance(id:*):IndexedObject {
				if (_instances[id] == null) {
					_instances[id] = new IndexedObject(new Key)
				}
				var instance:IndexedObject = _instances[id] as IndexedObject;
				instance._id = id;
				return instance;
			}

			/**
			 * Returns all of the created instances as an array.
			 */
			public static function get allInstances():Array {
				var array:Array = [];
				var obj:IndexedObject;

				for each (obj in _instances) {
					array.push(obj);
				}
				return array;
			}

			/**
			* Removes an item from the list of instances.
			* Actually, doesn't quite work because an instance referenced by a variable
			* outside of the class could still hold a reference to the deleted instance.
			*/
			public static function deleteObject(id:*):void {
				delete _instances[id];
			}

			/** Just used for testing */
			public var name:String;

			/**
			 * Constructor can't be used by outsided classes.
			 */
			public function IndexedObject(key:Key) {
				// Initialize code
			}
		}
	}
	class Key{}

So essentially what’s happening here is the Singleton’s getInstance() method is being replaced with one that allows you to specify a particular instance. Any class could create new instances or access the same instances provided they had the same id. Here’s a little demo. I’m using a name property to show the example.

	var thing:IndexedObject = IndexedObject.getInstance(5);
	thing.name = "thing 5";

	thing = IndexedObject.getInstance("foo");
	thing.name = "thing foo";

	for each (var obj:IndexedObject in IndexedObject.allInstances) {
		trace("IndexedObject.getInstance(",obj.id,") =", IndexedObject.getInstance(obj.id).name);
	}

Results in:

IndexedObject.getInstance( foo ) = thing foo
IndexedObject.getInstance( 5 ) = thing 5

Voila. The “indexed object”. I think for me the jury is still out on whether this is a good idea. It seems like it might be kind of a hack since it, like Singleton, is essentially just a complicated implementation of global variables but even more so and without Singleton’s benefits. It also intuitively feels like it could be very useful. Either way, I’m proud of it.

So what do you think? What would you use this for? Is it a hack? Pattern or anti-pattern?


getNumberAsHexString(255); // 0xFF
getNumberAsHexString(0xABCDEF); // 0xABCDEF
getNumberAsHexString(0x00FFCC); // 0xFFCC
getNumberAsHexString(0x00FFCC, 6); // 0x00FFCC - Uses 6 as a minimum number of hexits

I’ve added the code to the AS3lib as  as a global function. I may move it to a utility class later on. You can view the source on Google Code.

Incidentally, in a moment of bug-fixing frustration, I found this article on O.C.A.S. which describes how the same functionality is already built into the toString() method! However, the work isn’t completely wasted since my version includes the option to show leading zeroes and adds “0x” at the front of the result.

I’m doing a little exercise in a book that makes a textfield in which each letter can only be entered once. Not very useful, more of a teaching thing really. However there’s a bit of code that says:

var tf:TextField = event.target as TextField;

I don’t understand this at all! What the hell is event.target as TextField? Anyway here’s the full code for context’s sake:

package com.FoundationAS3.ch6 {

	import flash.display.Sprite;
	import flash.text.TextField;
	import flash.text.TextFieldType;
	import flash.events.TextEvent;

	public class PreventDefaultTest extends Sprite {

		public function PreventDefaultTest() {
			var tf:TextField = new TextField();
			addChild(tf);

			tf.width = stage.stageWidth;
			tf.height = stage.stageHeight;
			tf.type = TextFieldType.INPUT;
			tf.wordWrap = true;

			tf.addEventListener(TextEvent.TEXT_INPUT, onTextFieldTextInput);
		}

		private function onTextFieldTextInput(event:TextEvent):void {
			var tf:TextField = event.target as TextField;
			if (tf.text.indexOf(event.text) > -1) {
				event.preventDefault();
			}
		}
	}
}

Thanks,
-Neal

My response after the jump.

Neal,

First of all, let me say that preventing the default event handler, e.g. for a TextField, is rarely used and isn’t worth spending a lot of time discussing.

On the other hand, the as operator (along with the is operator and the type cast) are totally useful and you should learn all about them. First, let me cover is:

is

is is an operator that evaluates whether some object is of a certain type. The syntax is [object] is [type]. The term ‘type’ is similar but not interchangeable with ‘class’. A type can refer to not only the class of an object, but also the super-classes it extends and interfaces it implements. An example:

var sprite:Sprite = new Sprite();
trace(sprite is Sprite); // true, because the sprite object is an instance of Sprite
trace(sprite is DisplayObject); // true, Sprite is a subclass of DisplayObject
trace(sprite is MovieClip); // false, MovieClip is a subclass of Sprite.
trace(sprite is IEventDispatcher); // true, DisplayObject extends EventDispatcher which implements IEventDispatcher.

Note that sprite is not a MovieClip but a MovieClip is a Sprite. Because MovieClip extends Sprite and contains all the same methods and properties as Sprite but not the other way around.

Note: the instanceof operator commonly used in AS1/2 still exists in AS3 but is for all practical purposes deprecated by is (although still useful if you’re manipulating prototypes). typeof is also related but shouldn’t be used in place of is because it only returns strings for primitive data types like Object and String. In order to get the actual name of the class that an object is an instance of, you can use the flash.utils.getQualifiedClassName() global function.

as

as functions similarly to is except that it actually will attempt to coerce the object into the data type that you ask for. Coercion, AKA type conversion or casting, is the act of changing the data type of an object.

With the case from your book, an Event object has a target property which refers back to the object that originally dispatched the event. Since the Event object is designed to be sent out from all different types of objects, the target’s data type is Object (the mother of all the other classes). So, if the variable you’re defining is a TextField, you’re expecting an object with a text property. Object, doesn’t have a text property so you have a dilemma. The solution is to cast the object into the type you want it to be, basically forcing it to be more specific.

var textField:TextField = event.target; // Throws compile error because target is an Object not a TextField

var textField:TextField = event.target as TextField; // OK! as long as the event target actually is a text field

Going from a more generic type to a more specific type is called a downcast. Going from a more specific type to a more generic type is called an upcast. Upcasting in ActionScript, as with most other languages, is done automatically and is always safe. e.g. a Sprite can be used as a parameter for a function that requires a DisplayObject. Downcasting on the other hand is unsafe meaning that you can’t always guarantee that it will work. A DisplayObject is not necessarily a Sprite.

When an attempt to downcast with as fails, the value returned will be null:

var string:String = new String();
var textField:TextField = string as TextField // string can't be converted. textField will be set to null

If you’re not sure whether your object is the right type (and you should never assume it is) check to see if the value is null before proceeding:

var typedObject:TypedObject = mysteryObject as TypedObject;
if (typedObject != null) {
	// conversion was successful! do something with typedObject
} else {
	// conversion failed
}

Type casts

Another way to do this with slightly different results is by type casting. Type casting works with the syntax Type(object) and is functionally similar to object as Type. The only difference is with a type cast, you get a runtime error if the coercion fails.

var textField:TextField = TextField(event.target); // if event.target is a TextField, you're good. If not, you get an error.


you can also shortcut like this:

TextField(event.target).text = "foo";

Conclusion

Why are objects like event.target given such generic data types? The idea is that you want to minimize the requirements of a property, parameter, or function to maximize the number of objects that will qualify thus making your program more flexible. In other words, strive to use the most broadly defined data types that you can get away with.

For example, say you’re creating a simulator program for getting a person from their home to their job. You may be tempted to define your modeOfTransportation variable with a type of Car. But down the road the company you’re working for wants to create a more green image for themselves and suggests using alternative modes of transportation. If you’re code is based on Car, it’s limited in what you can do with it. However, if you had used a Vehicle type (includes Car, Bike, Motorcycle, Donkey) instead, you may not have had a problem. Using interfaces like IConveyance makes your program even more flexible because you can include non-vehicluar objects like MolecularTransporter, Feet, and CrowdSurfing as long as they satisfy the interface. In fact, I would suggest as an experiment that the next time you start a project, try coding all the interfaces first before you move on to coding specific classes. You’ll be surprised at how flexible it is and how it forces you to consider the roles of your classes from a higher level.

Though you should strive for generic types, sometimes you will need to get specific. If your program has a gas station simulator in it, the fillTankOfVehicle() method might require a MotorVehicle class (includes Car, Motorcycle, Plane) instead of simply Vehicle. Still, you should only get very specific when your program requires it. If you are making a racing program, use F1RaceCar only when a simple Car won’t cut it.

I hope this helps! This is definitely a difficult topic even for experienced programmers to grasp!

AS2 EventDispatcher

Note: I just wrote about this in my previous post about converting AS3 to AS2 but I wanted to repost it for easy search purposes.

Before I begin, I must stress to you, if there is any way you can avoid downgrading your code, you should avoid it! If it’s a matter of making two systems communicate, there are countless reasons that it would be better to upgrade your code from AS2 to AS3. There are even ways to host your AS2 code in an AS3 wrapper. In my case, an important requirement (that the deliverable absolutely must be AS2) was left out of the original scope of work due to a misunderstanding but anything that doesn’t cause project stoppage should be considered carefully.

I must also preface this article by reminding the reader that there is no 1-to-1 conversion from AS3 to AS2 (nor the other way around). There are loads of features added to Flash Player 9 that simply don’t exist in Player 8. Some things you’ll be able to convert with a simple find and replace. Some things you’ll need to re-create in AS2 or re-think completely. Some things you just won’t be able to do. This article only covers the stuff I ran across while converting my files and is by no means comprehensive. However, I hope it gives you a good starting point to work from.

Converting the document class

Since you’re a smart, cool AS3 programmer with a good sense of humour, I know you use a document class in your FLA files or a main application class for your FlexBuilder project. Right? Good. Of course, AS2 does not support document classes and all code must be run from the timeline. You have a couple of options here. You could move your document class to the timeline and remove the class specific portions of the code. Perhaps a quicker and easier solution is to modify your document class to take a reference to the root. So you have something like this on the first frame…

var documentClass:MyDocumentClass = new MyDocumentClass(this);

Just keep in mind that your document class will need to store a reference to the root that’s passed in as well as make references to things that were on the stage. For example…

public function MyDocumentClass(mc:MovieClip) {
   this._mc = mc;
   this.thingOnStage = _mc.thingOnStage;
}

Cleaning up syntax errors

The first step to take once you can compile your code is to run it and fix each compile time error one at a time. To save you the trouble of some of the more common ones I found, I created this list of common syntax problems.

Search and replace:

• void -> Void
• int and uint -> Number
• DisplayObject, DisplayObjectContainer, Sprite -> MovieClip
• public class -> class
• internal -> public
• protected -> private
• override -> (nothing)
• mouseEnabled -> enabled
• [obj] as [type] -> [type]([obj])
• [obj] is [type] -> [obj] instanceof [type]
• const -> var (or optionally, to implicit getter)
• Add underscores before MovieClip variables. e.g.: x, scaleY, alpha -> _x, _yscale, _alpha including:
  • alpha -> _alpha
  • x,y -> _x, _y
  • scaleX,Y -> _xscale, _yscale
  • mouseX,Y -> _xmouse, _ymouse
  • visible -> _visible
  • currentFrame -> _currentFrame
  • totalFrames -> _totalframes

Add:

• import statements for classes within the same package (not required in AS3)

Remove:

• import statements for AS3 packages (e.g. flash.display.* )

Convert:

• _xscale, _yscale, _alpha – Convert from decimal to integer (0.2 becomes 20).
• Convert Timer to setInterval
• Convert Loader to MovieClipLoader
• Remove package declaration but copy the package name and put it before the class name. Also remove closing } from the end of the file.
  e.g. :

  package com.mysite.package {
  	public class Foo {
  	 	//...
  	}
  }

  becomes

  class com.mysite.package.Foo {
  
  	//...
  
  }

Other tips

Events are a huge part of AS3 development and Player 9 supports a fully event-driven development style. Unfortunately, AS2 is heavily lacking in this department and while events can be recreated in AS2, it lacks method closures and bubbling that make AS3 so nice. To downgrade, I did two things. First, I recreated the event dispatcher in as2 and second, I made heavy use of event callbacks and the Delegate class.

com.mimswright.events

In order to change as little of the event code as possible, I looked back to previous AS2 projects where I had used Danny Patterson‘s EventBroadcaster classes. These classes worked roughly the same as the EventDispatcher class in AS3. I took the liberty of brushing up the code and making it look as much like the AS3 EventDispatcher as I could. I’m making it freely available for use.

as2eventdispatcher

event callbacks

Most of the events you’ll probably be using must be triggered by callbacks in AS2. That is, you define a function that gets called when an event takes place like

onMouseMove = function ():Void {
   //do something
}

Keep in mind that in AS2 there are no method closures as there are in AS3. That is, a function isn’t necessarily executed in the scope that it exists in. In even simpler terms, a function doesn’t know what object it’s associated with. Because of this, code such as button.onRelease = object.handleClick; executes the handleClick function from the button context and my not work properly. Fortunately, AS2 code can make use of the mx.utils.Delegate class – specifically, the Delegate.create() method. This artificially maintains the context in which the function was supposed to be called. So your code should look like button.onRelease = mx.utils.Delegate.create(object, object.handleClick);

I hope this has been a helpful start for you poor souls who are faced with the challenge of down-converting code. Good luck to you and feel free to add your experiences to the comments.

My current configuration is Mac OS X 5.2 + TextMate 1.5.7 + Flex SDK 4.0.0.3504. I have two shell scripts in place:

1. /usr/bin/mxmlc
2. A TextMate run bundle set to a hotkey, “command + R”
3. I’ve also have my Flex SDK set to the absolute path of: /Developer/SDKs/Flex/4.0.0.3504

This configuration requires a flex-config.xml in the same directory as the AS3 class file that you’re compiling. When you run the TextMate script (or something similar in your Terminal shell) it will compile the filename you pass in and default to using a config.xml which acts as a local flex-config.xml file. All of these can be customized as needed.

Example Flash 10 3D cube rotation:
[kml_flashembed movie="http://www.calebjohnston.com/storage/fl10_examples/01_cube_rotation/CubeRotationExample.swf" height="260" width="410" bgcolor="#FFFFFF" /]

Obviously, the above swf won’t work without Flash player 10 installed.

Download the source here.

I may be in the (rare?) position of being highly interested in two disparate technologies. The first being an online scripting language standard governed by ECMA (used in Javascript & Actionscript). The second, an open standard for real-time rendering governed by the Khronos Group (OpenGL). In recent days these two languages have faced most unfortunate developments. First the ECMA script 4…

On Nov 7, 2006 Adobe announced the contribution of their ECMA scripting engine to the open source community under the name “Tamarin”. Tamarin is also being used as the JS scripting engine for Mozilla Firefox under the name “SpiderMonkey“. It seemed like a good idea at the time of release. But now look at the situation: we have AVM2, directly connected to Firefox AND the ECMA committee –slowing the progress of Actionscript and the Flash Player (and the internet for that matter). Needless to say, this is a disappointment. But it doesn’t end there…

Though having plenty of contributors, the realm of real-time rendering is primarily controlled by Microsoft, Nvida, ATI/AMD, Apple, and (more recently) Intel. Microsoft hasn’t really contributed to the Khronos Group because long ago they decided to pursue their own 3D graphics rendering API known as Direct3D. The evolution of OpenGL has become painfully slow while DirectX and Direct3D are becoming the (de-facto) standard. Finally, the Khronos group promised to improve the long lost API by introducing an object-oriented structure in stark contrast to its current state machine model. That was in October 2007. Last week the specification was finally unveiled and it remains largely the same. Not only is this a big let down, but it will definitely damage all future 3D software and game development releases for non-Windows platforms (including future consoles). Very unfortunate.

DISCLAIMER: Both of these developments are FAR more complex than what this post outlines -and there’s justification behind both developments. But on the whole, they both seem bad for everybody (or just me?).

Animation
Animation in Papervision3D can be performed the exact same way animation would be performed in 2D. Simply apply any tween or algorithm to an object property (like x, y, rotationX, scaleY, etc) and re-render the scene. But, for imported animations its not quite that simple. Lately Moses’s GoASAP package is being adopted in testing for the Papervision engine. It could soon become adopted by the system.

The Collada DAE Parser
Imported animations come in plenty of flavors but must conform to the same system. That’s the reason the animations package exists. Papervision has long supported externally created 3D assets. You’ll find those file parsers in pv3d.objects.parsers. Although, these importers are nice to have, a big part of Great White was the introduction of the open source project ASCollada. ASCollada is an amazing parser for the standard 3D asset interchange format known as Collada. Collada files are basically very dense XML files that use a .dae file extension. Collada files can be exported from Maya, 3D Studio Max, Blender, Google Sketchup, and XSI. However, level of support for those programs probably follows this order: 3D Studio Max, Maya, Blender, Google Sketchup, XSI. Also, if you’re importing MD2 models, the MD2 file parser will import most animations as well.

You can try it out using the DAE class like so:

import org.papervision3d.events.FileLoadEvent;
import org.papervision3d.objects.parsers.DAE;
daeScene = new DAE();
daeScene.addEventListener(FileLoadEvent.LOAD_COMPLETE, onSceneGeometryLoaded);
daeScene.addEventListener(FileLoadEvent.ANIMATIONS_COMPLETE, onSceneAnimationsLoaded);
daeScene.load("your_scene.dae");
var animChannel:AbstractChannel3D = daeScene.getAnimationChannels()[0];
var frame:uint = 20;
var animObject:DisplayObject3D = animChannel.defaultTarget;
animChannel.updateToFrame(frame, animObject);

Render Statistics
Papervision records all the primary rendering tasks. If you want to monitor rendering statistics, you can have them captured when you execute the BasicRenderEngine instance method “renderScene().” When traced, a typical render report will appear like this:

ProjectionTime:0 RenderTime:1 Particles:0 CulledParticles:0 Triangles:38 ShadedTriangles:0 CulledTriangles:82 FilteredObjects:0 CulledObjects:0

You can use this information to determine how well your scene is rendering. And it could give you ideas on how you can improve rendering by adjusting camera settings, culling plans, and clipping.

Optimization
Great White has gained many huge performance advantages over previous versions of Papervision. One important advantage is that nearly all materials will render a surface to BitmapData. This is great because, as of Flash Player Update 3 (9.0.115, mid-2007) Multicore CPU support has been added to much of the BitmapData operations.

Clipping is a flag added to the Viewport3D constructor in Great White that will force the engine to perform clipping of all objects outside the the viewing rectangle (the viewport). This feature may seem obvious, but a lot of public engines neglect this.

Culling Algorithms
Drawing is the most expensive process that Papervision performs. As such, there are a few different standard methods for removing items from the render queue in any 3D drawing API. This helps speed up render times by removing renderable triangles that would otherwise be drawn. Papervision3D performs backface culling, view frustum culling, and contribution culling but NOT occlusion culling. Occlusion culling is a huge process that is more built into accelerated APIs like OpenGL. Though it can be very difficult to perform well, it can also add extrordinary benefits to rendering performance.

MovieClip Materials
Papervision3D supports interactive, animated, and smoothed MovieClip materials. However, those features come at a cost. You may already be aware that BitmapData smoothing (anti-aliasing) is slower than normal BitmapData rendering. Anti-aliasing algorithms are simply expensive operations and thats the bottom line. The other two features are performance hogs because they require that the Flash player to update the surface BitmapData object on each frame update –instead of reusing the original object that was derived from the MovieClip.

Relative Performance
I’m currently coding lots of Flash player performance tests as they relate to Papervision. Right now I’m only using the following methods for testing: Math.sqrt(), Math.sin(), Matrix3D.multiply3x3(), and BitmapData.draw(). The test is simply a for loop that iterates 9999 times. It looks interesting and helps me make another point about PV3D performance. I’ll have to publish this application elsewhere, but for now here’s a sample of what I’m finding:

Figure A: Performance timetable for 4 operations in a for loop lasting 9999 iterations. BitmapDataObject1 is 40×40, transparent and BitmapDataObject2 is 600×600, transparent. They both draw a single purple circle.

As you can see bitmap drawing is the most expensive operation here. In almost every instance that I can think of, drawing will be the most performance intensive activity in any 3D rendering API. I could explain that here, but it would probably double the size of this post. ;)  In a nutshell, it always helps to render only when you actually need to feature interaction and/or animation. Additionally, actively perform any reasonable operation to limit the number of objects in the scene. Again, the library does a lot for you there, but gains can always be made. Also, a little experience will show you that keeping the renderable area small will help also.

The Papervision3d source SVN location includes the standard AS3 version of Papervision3D (version 1.7 as of this writing). If you look at the branches folder inside trunk you will find version 2.0 which is code-named “Great White”. This series is focused on that branch, and NOT version 1.7. Also, its important to know that Great White is probably the fastest and most frequently changing part of the Papervision source and thus details in this article will likely change over time.

Also, as a convention in these posts, I’ll be putting direct references to actual Google Code hosted repository files inside this page. If you don’t wish to open that repository each time you want to know the path of a class, then simply mouse over the link and look at the link address or the tool tip that shows up for the link. All references to Papervision3D classes assume that all uses of the term “pv3d” refer to the root Papervision3D package.

All Flash demonstrations are interactive. After focusing on the Flash applet, you can use the following key controls to control the camera.

Please note that nothing will promote your understanding of the code better than just reading it yourself. Although that may seem daunting, you’ll end up doing it anyway if you really get into the project. A good place to start might be reading the comments for classes in the folder pv3d.core.proto. If you’ve happened upon this page but are unfamiliar with computer graphics from a technical standpoint, please read Part 1

Geometry
In Papervision, all geometry is basically stored in the form of vertex data (Vertex3D). Collections of Vertices are stored in GeometryObject3D instances. Every DisplayObject3D class contains object information (such as location, transformation, orientation axis, etc) AND a reference to a GeometryObject3D instance. The DisplayObject3D class is the building block of all 3D data in Papervision –much like the flash.display.DisplayObject class is the building block of a 2D stage. However, one important difference is that a DisplayObject3D will not contain any rasterized visual data (as the DisplayObject does in its graphics object). It contains only data that is used by the rendering engine (BasicRenderEngine) and the object’s material (* MaterialObject3D) which is used to draw the object onto a Viewport3D object.

*Note: the actual method performing all drawing operations is NOT MaterialObject3D.drawTriangle but instead any of its subclassses that are overriding that method (for example ColorMaterial.drawTriangle).

Texture Mapping
Up until now, all discussion about 3D rendering has excluded the use of images used on geometric surfaces. This feature, called texture mapping, is very widely used. Unfortunately, it can also be quite an expensive process in terms of CPU cylces. Texture mapping has also evolved to allow for plenty of visual effects like bump mapping, normal mapping, displacement mapping, light mapping and more.

As you may recall from Part 1, all surface geometry in Papervision is divided into triangles. However, since images used in texture mapping are rectangular, something must be done to determine how the image can be mapped onto triangles in order to render the rectangular map as a single image. This is where the UV coordinates come in. A UV is simply a 2D coordinate that represents a location on the texture map that is associated with the 3D point on a triangle. Figure A1 shows this relationship.

Figure A1: Three example UVs for texture mapping a rectangular plane.

In Papervision, all the actual drawing commands exist in the material class being used for an object (as I mentioned above). Please note that two options for texture mapping exist. There’s ‘normal’ texture mapping which is also known as ‘affine‘ texture mapping. And then there’s ‘precise’ texture mapping which would be perspective correct. Normal texture mapping is a bit less accurate but far faster in rendering then precise textures. Exhibit A2 shows an example.

Exhibit A2: Normal (left) vs precise (right) texture mapping in Papervision3D 2.0

[kml_flashembed movie="http://www.calebjohnston.com/storage/posts/textureExample.swf" height="250" width="450" /]

Materials
A Material is a term borrowed from 3D development tools (like 3D Studio Max) that describes a collection of properties that will determine how a 3D surface will be rendered. Materials can become very complicated in production 3D rendering tools, but in Papervision a material has only a few properties. Those properties will determine whether lines, fills and/or a bitmap is drawn and how they’re drawn. The real key component of all materials is the drawTriangle method which is called by the engine during the render cycle.

Lighting and Shading
Light simulation is probably one of the most intricate and complicated aspects of 3D rasterisation. Other forms of computer rendering (like ray tracing) don’t treat lighting the way the rasterisation technique does. The reason is simple, performance. So in order to mimic light phenomena using rasterisation, shaders can be used. With the Great White branch of Papervision, lighting and shading have been added. Outside of Papervision, the term “shader” sort of has multiple definitions. Shaders are used in 3D development tools to determine how light will appear on a surface. But in real-time rendering APIs (like OpenGL and Direct3D) a shader is used to modify the graphics pipeline. There are actually several languages that govern shader authoring. Even Adobe has their own brand of shader language called Adobe Image Foundation. Although shading and lighting are rather complicated features in GPU accelerated APIs, in Great White they’re actually much simpler.

With Papervision, shaders are probably most useful for applying native flash effects (filters and blend modes) to any desired surface. Although, filters are not fully supported yet. Aside from that, applying a shader to a material is basically the same as applying a gradient-like light map to the BitmapData surface. So if you understand gradients and BitmapData objects in Flash, you basically understand Papervision shading as well. There are really 4 types of light maps you can use and those are Phong, Flat, Gouraud, and Cell. For each of those light maps there is a shader. There is also one other shader that can create an environment map. Its the EnvMapShader. It allows one to pass in bitmap objects that are used in combination with the surface texture map. Also you can use bump maps in Papervision3D shaders. See the BumpmapGenerator class. Exhibit B illustrates a simple example of various shaders. While this is not really the same ‘shading’ that happens in video games, with Flash 10, shading could definitely change radically in Papervision.

Exhibit B: Shading examples in Papervision3D 2.0

[kml_flashembed movie="http://www.calebjohnston.com/storage/posts/shadersExample.swf" height="250" width="450" /]

Its also important to note that shading requires a light source. Unlike other popular 3D APIs, there is no default ambient light. And any light sources that are used are not a part of the scene. Instead you must add a light source to the shader and its position is used in determining what the light map looks like. At the time of this writing there is only one light source supported per shader in Papervision3D. Also there is only one type of light to choose from -a point light.

Cameras
Cameras aren’t that complicated in Papervision3D. There are three types of Cameras: free, target, and debug. A free camera is totally unattached to anything that exists in the environment and can be moved ‘freely’. But a target camera will have a focus object within the scene. That object can be moved freely, but the camera will always come along. It works just like a focus camera object would work in a 3D development tool like 3D Studio Max or Maya. And thus a key aspect of that behavior is that if you want to translate a Camera3D object, it will actually rotate about its focus object. The last type of camera (debug) allows for key control, so that you can move the camera around as desired. This is highly useful when you’re building a complex scene or importing geometry from an external editor.

The only three camera-specific properties you can manipulate to control the view are zoom, focus and field of view (fov). The fov is in degrees. Normally 60 is representative of a normal 35mm camera lens. But the debug camera defaults to 90 degrees. Zoom and focus can be determined based on the fov and the camera’s distance to the near clipping plane. Exhibit C demonstrates the interaction of the fov and focus value. Also, here are some rather crude numbers for comparison:

Note: all camera focus values are used with a default debug zoom value of 24. Field of view values are in degrees.

Exhibit C: Demonstration of camera field of view and focus. Use keys r and f to increase and decrease the fov respectively.

[kml_flashembed movie="http://www.calebjohnston.com/storage/posts/cameraExample.swf" height="250" width="450" /]

Stay tuned for more feature dissection in Part 3. In the meantime, download examples source files here.