Now, I wouldn’t really recommend using this code in a project. There are ways to do the same thing that are much more readable and less error prone. Instead, I thought it was an interesting experiment to show off some of how AS3′s syntax works for those of you who may not have seen something like this.

What’s happening here? Let’s break it down.

• ["Alpha", "Bravo", "Charlie"] – Here we are instantiating a new array and populating it with three strings. This is essentially the same as:

  var a:Array = new Array();
  a[0] = "Alpha";
  a[1] = "Bravo";
  a[2] = "Charlie";
  

• [...] – next is another pair of square brackets. This is an array access operator. In other words, everything between the two brackets will be evaluated as the index of the array to retrieve.
• int(...) – This is an explicit type-cast to an int. That means that everything inside those parentheses is evaluated and flash attempts to convert from whatever data type it is to an integer. In the case of decimal numbers, they are rounded down so this is similar to using Math.floor().
• Math.random() * 3 – random() of course produces a random floating point (decimal) number between 0.0 and (almost but not quite) 1.0. Multiplying that number by 3 (the length of the array) produces a number between 0.0 and 3.0 (technically, between 0 and 2.99999999etc).

The result, an array is created with three strings, a random number between 0.0 and (almost) 3.0 is generated, it is rounded down to an int between 0 and 2, that number is used as the index of the array to look up. The result will be randomly one of the three strings.

I hope you found this interesting!

John Lindquist commented almost immediately that there is a project on github designed to collect these sorts of useful little snippets of code. It’s called as3-utils. Check it out!

This week’s snippet, isRoughlyEqual(), provides a simple way to find out if two numbers are in the ballpark of each other.

I’ve added it to the as3-utils project too.
http://github.com/mimshwright/as3-utils/blob/master/src/utils/number/isRoughlyEqual.as

Anyway, here’s my first contribution. It’s a simple little function that limits a number between an upper and lower limit.

BTW, I used gist.github.com for this but snipplr is good too. If you know of others, leave a comment!

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

I’ve been doing a series of dynamic, engaging, interactive, educational and disturbingly sexy workshops on topics from the new AS3 Bible. These workshops are hosted by the fearless FlashCoders NY user group. If you’re in NYC and want to drop by, check the meeting announcements. Having a copy of the book isn’t required! (But I sure recommend it, duh!)

I give the workshops every other Wednesday, give or take. Tonight’s is on Pixel Bender! Be sure to stop by!

As an aside, you may be curious what I’m up to. Actually, you aren’t, but I’ll tell you anyway because I’m amped. I’m juggling several iOS projects on iPhone 4 and iPad, I’m days away from launching an amazing collaboration with artists/directors Radical Friend, the creators of openFrameworks, and the talented folks at The Science Project — an experimental art piece driven by Unity and oF. And what the hell, I’m trying to learn 3D modeling (again) (finally). I heard that I might be giving a series of iOS dev video training episodes… stay tuned if you want to hear more!

Turning a DisplayObject into a 3D DisplayObject is as simple as assigning a value to its rotationX, rotationY, rotationZ, or z properties. But how do you turn it back? I tried giving all these properties a value of 0, but after their animations completed they were already 0. An object at z=0 still renders in 3D, using bitmap caching. Setting these values to NaN was no better.

The solution I found is to null out the 3D transformation matrix and assign a 2D transformation matrix. This can be accomplished like so for a DisplayObject named sprite:

var matrix:Matrix = new Matrix();
matrix.translate(sprite.x, sprite.y);
matrix.rotate(sprite.rotationZ);
sprite.transform.matrix3D = null;
sprite.transform.matrix = matrix;

In this code I simply drop the transformations that are inapplicable to 2D space. This is fine when your object is already coplanar with the stage.

Anyway, quick tip if this ever had you scratching your head too.

Read the article on Photon Storm

The article shows that Flash Player is already fairly optimized for graphical composition operations when compared to blitting. Both showed similar framerates. However, the cacheAsBitmap operation caused an exponential increase in memory consumption when the number of sprites on stage increased. Ironically, the comparison was run by the creator of the Pixel Blitz library who, I’m sure, had a difficult time presenting the results.

There are some good details in the article so if you’re interested, read the whole thing before you decide if you agree.

Have you done any work with bit blitting or sprite sheet animation? Have you found it to be beneficial? Tell us your thoguhts.

I’m going to keep one as a trophy but if you can read chinese and you’d like a copy, let me know and I’ll send you a present*!

*(If you’re outside the US, i’ll ask you to pay for shipping)

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.

This version will not be backwards compatible, however, there’s finally some Decent Documentation!!! There’s also a new blog devoted to KS.

GO GET IT NOW!

Here’s some of the new features. You can view all of them by checking out the change log.

• Usability
  • REFACTORED all classes with usability and stability in mind.
  • UPDATED all ASDocs
  • ADDED several new methods in the TweenFactory for easy tween creation.
• Synchronizer and Time
  • REFACTORED The way time is handled throughout.
  • ADDED ISynchronizerCore and example core classes. This allows advanced users to switch between different methods of timing (e.g. enterframe or timer based)
  • ADDED FrameRateUtil for getting instantaneous and averaged framerates of the system. The FrameRateView now makes use of this class and has more options.
• Action Architecture
  • REFACTORED action classes and extracted several interfaces from them.
  • ADDED jumpToTime and jumpByTime functionality to actions.
  • ADDED Looping via a new group called KSLooper.
  • REMOVED complicated and rarely used action triggers from AbstractAction.
  • ADDED togglePause() method and progress variable to AbstractAction (for getting percentage complete of an action).
• Tweens
  • CHANGED constructors in KSTween. Emphasis is now on using TweenFactory.
  • IMPROVED Object parser in TweenFactory
• Action Groups
  • ADDED Syntactic sugar to the group constructors. using an array in the constructor for a parallel group adds a sequence and vice versa.
  • ADDED totalDuration to groups to show the duration of all child actions in a group.
  • ADDED KSRandomGroup.
  • REMOVED KSSteppedSequenceGroup because it seemed kinda useless.
• Loading Actions
  • REFACTORED Loading actions. Now they’re much easier to use and more powerful.
  • ADDED KSLoadQueue for quickly creating a class to load files from the network in a batch.
  • ADDED the resultList property to the ILoaderAction interface so that you can quickly access the loaded files in a batch.
• Misc
  • RENAMED several classes and reworked package structure
  • ADDED KSAsynchronousIteration for running processor-intensive for loops spaced out over a period of time so that they are essentially asynchronous.
  • FIXED several minor and major bugs.

But resource bundles can’t help you in every scenario. I often find myself needing to construct a sentence with live data inserted. For this, the resource strings are less helpful. For example, how would you write:

"At " + time + ", you received a message from " + userName + "."

With resource strings, you would have to do something like

at=At
message=, you received a message from
period=.

Which completely negates the whole point of using resource bundles. What to do?

Token replacement

What I really wanted was a way to inject data into the string. I’ve seen this done by use of tokens in other languages like Objective-C so I thought I’d give it a try. The result was surprisingly lightweight.

I created this utility that lets you use tokens (delimited by % signs) that can be replaced by live data when you retrieve the resource. Using this class, the example above would look more like this:

receivedMessage=At %time%, you received a message from %userName%.

// then in your code
trace(ResourceStringUtil.getResoureceStringWithTokens("receivedMessage", {time: "11:49", userName: "Mims"}));

// displays
At 11:49, you received a message from Mims.

Here’s the source code Feel free to use it and modify it for your purposes.

I’m very pleased to announce that one of my latest projects has just gone live. The Deepening – Select Your Own Adventure Edition has just gone up on Atom Films. Go give it a look, it’s hilarious.

The video is a Good Cop / Bad Cop action show where you get to choose what happens next. It was created by the brilliant Duncan Brothers who asked me to help build the Flash portion of it. Enjoy!

deepening.atom.com

Runtime Environment

SWF Files
Swf files are compressed, multipurpose packages designed to contain the following data: raster and vector graphics, video, audio, text, fonts, animation, and actionscript code. Swfs can be loaded at runtime whenever necessary and can use both static and dynamic linking based upon the compiler settings. The runtime environment uses security sandboxes for loaded swf files. The security settings primarily limit the extent of filesystem access and cross-domain access that swf files can use. Adobe has provided the swf file format spec and has recently provided the FLV video format spec and has declared that they will provide the RTMP spec as well.

Flash Player & AVM2
The Flash Player runtime is a very light-weight, virtual machine and handles system calls. The Flash Player includes both AVM1 (AS1, AS2, for Flash versions 1-8) and AVM2 (AS3 for Flash 9,10+) which processes compiled Adobe Bytecode (ABC). The term AVM stands for “ActionScript Virtual Machine”*. The Flash Player uses a Deferred Reference Counting (DRC) mechanism combined with a conservative mark/sweep garbage collector. The Adobe VM uses both JIT compiling and code interpretation and may benefit from compile-time bytecode optimizations based upon compiler input parameters. AS3 computational performance is generally closer to Java than Javascript [source]. The player also maintains a variable framerate that reflects the time consumed for each frame update [source]. Each frame update consists of multiple stages that include internal player processing, rendering, and author script processing. The program framerate is the principle metric reflecting application performance.

Development Environment

Actionscript API
The Actionscript API is divided up amongst the Adobe AIR environment, the Flex environment, and the Flash environment and the Flash Player. The source for all the packages are divided up amongst swc files. Swc files are pre-compiled catalogs of classes and assets. They are similar to swf files but they are used for compile-time dependency resolution. Furthermore, the native swc’s predominantly contain code and not visual assets. An overview of the Actionscript packages is kept up to date in the Adobe Live Docs.

The Flash IDE
The Flash IDE was designed for designers, artists and animators. So, it is equiped with a layer system which reflects the stage display list and a hierarchical timeline which reflects the temporal nature of the runtime. The objects placed on the stage are represented by the timeline and can be “tweened” (using runtime interpolated 2D geometric transformations or custom shape morphs). The same timeline is also used for object creation and destruction. All stage instances are confined to a small set of native data types including: MovieClips, Sprites, Shapes, TextFields, Videos, and Bitmaps. The IDE also has a library that contains source objects for all stage instances and even instances that aren’t used on the stage. Flash projects often have several build targets (compiled swf files) that use parts of the project codebase. After Macromedia was purchased by Adobe, the Flash authoring environment has been updated to provide much better interoperability with the Adobe Creative Suite.

Adobe Flex Builder
Flex Builder is an Eclipse-based Actionscript IDE for writing and compiling swf files. Flex Builder is primarily designed to build “Flex” projects which can be written in an interface tagging language known as MXML. MXML is a declarative XML langauge used to define interface elements in a project. MXML files provide the “view” in the MVC software design pattern. Flex Builder also provides plenty of useful features like code completion, syntax formatting, active debugging, memory profiling, and project building that expose errors and warnings during development time. Because the Flex framework is not bundled with the Flash Player, Flex projects must statically link to all swc assets specific to Flex which amounts to greater than 500kb. This is very unnatractive for most users, thus Adobe has provided means by which the download can be significantly decreased. Flex Builder is also used to deploy applications for the Adobe AIR platform. Adobe AIR is a desktop runtime that combines webkit with the AVM2 portion of the Flash Player. AIR can be likened to a closed source Java SE runtime but provides a smaller learning curve and greater accessibility than what comes with the Java ecosystem.

Compiler
Since Adobe has launched the Flex platform they have provided free access to their Flex and Actionscript compiler and SDK. They have also provided open source projects under the Mozilla public license. The compiler (mxmlc) provides an impressive amount of flexibility and customization for swf compiling. It can be configured with command line options or a configuration XML file.

* correction 09-12-2009, I had previously stated that the term AVM meant “Adobe Virtual Machine”, this is a mixup. It actually means “ActionScript Virtual Machine”. Thanks dbam.


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.