Later on I ported it to AS3 for a game that was never published. I made these:

Then, I forgot about it, for a long time, but I just came across it again! It’s actually my own 3D library, back in the days before I had heard of Papervision or Away3D, or any of the others. It draws the polygons using Graphics. That part is worthless.

However, I haven’t seen the dihedral angle structure that allows me to define the solid to open and close in other code. Perhaps this will be useful to someone. If you would like it, then you’re very welcome!

The code is here: https://github.com/alecmce/ptolemy3D/tree/master/src. The unfolding parts here.

In my last blog post, I argued that Robotlegs is poorly equipped to cope with asynchronous processes, and offered an extension to RobotLegs to seek to solve this problem, "Async Processes Extension". This extension follows in the footsteps of other interesting libraries, such as Shaun Smith’s Oil Extension among many others.

Reflecting about Processes

Since I wrote that code and blog post, I have been reflecting on my approach. I have a few problems with it:

• RobotLegs is fundamentally lightweight. It is my framework of choice because it’s hardly a framework at all. The Processes extension adds a lot of conceptual overhead and does a lot of work under-the-hood.
• It separates the concept of a process from the concept of a command, but it can often be the case that previously synchronous code can become asynchronous (for example: when moving from mocked data to live data), or the other way (for example: once data is pre-loaded that was previously loaded just-in-time). Refactoring between commands and processes seems more trouble than it’s worth.
• The under-the-hood part of the Process class means that it’s impossible to duck-type a Process. Duck-typing is good insofar as you know a framework that accepts duck-typable object has minimal dependencies.

These criticisms of the library led me to think about a more lightweight approach.

The Central Premise of Process

The central premise of my critique of asynchronous code is that this sort of code is bad because the Command contains both its own logic and sequencing logic:

// pseudo-code!

class Context
{
	signalCommandMap.map(runSecond, SecondCommand);
	signalCommandMap.execute(FirstCommand);
}

class FirstCommand
{
	[Inject]
	public var runSecond:Signal;

	public function execute():void
	{
		process = new SomeProcess();
		process.run().addOnce(onComplete);
	}

	private function onComplete():void
	{
		runSecond.dispatch();
	}
}

It would be preferable to abstract the sequencing logic, so that the FirstCommand can just report that it has completed what it needs to do without having to know what’s next.

I have often found that you end up drawing diagrams for code written this way with each command in a box with arrows between them. I want a class that encapsulates that diagram, ensuring that the individual commands are truly agnostic with respect to their context in the application.

A Different Approach

If we abandon the notion of a Process, then how can we retain this separation? My second approach has been to abstract the sequencing logic into a class, called CommandFlow. The intention is to use it like this:

// pseudo-code!

class Context
{
	injector.mapClass(ComamndFlow, CommandFlow);

	signalCommandMap.execute(InitCommand);
}

class InitCommand
{
	[Inject]
	public var flow:CommandFlow;

	public function execute():void
	{
		flow.push(FirstCommand);
		flow.push(SecondCommand);
		flow.next();
	}

}

class FirstCommand
{
	[Inject]
	public var flow:CommandFlow;

	public function execute():void
	{
		process = new SomeProcess();
		process.run().addOnce(onComplete);
	}

	private function onComplete():void
	{
		flow.next();
	}
}

The command sequencing is abstracted into InitCommand, so that FirstCommand doesn’t need to know anything more than that it is part of a sequence. CommandFlow is a helper that allows asnychronous command sequencing to take place with a minimum of impact on the classes’ functionalities themselves.

Each CommandFlow injected into a command is a separate instantiation, so that if nested command logic is required, then it is possible. For example:

// pseudo-code!

class Context
{
	signalCommandMap.execute(InitCommand);
}

class InitCommand
{
	[Inject]
	public var flow:CommandFlow;

	public function execute():void
	{
		flow.push(FirstCommand);
		flow.push(LastCommand);
		flow.next();
	}
}

class FirstCommand
{
	[Inject]
	public var flow:CommandFlow;

	public function execute():void
	{
		flow.push(SecondCommand);
		flow.push(ThirdCommand);
	}
}

In this structure, FirstCommand will trigger SecondCommand and ThirdCommand before LastCommand is executed.

Payloads can be passed in explicitly through the push method, as CommandFlow exposes this method:

public function push(command:Class, ...args):Boolean;

A working demo of the code-in-action is provided in the github repository here.

Notes

At the moment it is not clear how to handle commands being pushed into a CommandFlow once the flow has been started with a next() call.

If the CommandFlow approach is to be useful, I will need to add branching into the CommandFlow class, and it could quickly become very difficult to maintain. Careful thought will be needed to cope with this.

After my previous post, Camille Reynders made several good criticisms. One important one is how to handle failures. I think that this might be handled elegantly through branching, or possibly through some CommandFlow.error method that is a general ‘abandon-ship’ method. I’m not sure yet how to implement this, since I’m not yet committed to using this sort of approach to solving asynchronicity problems.

Brian Heylin also pointed me towards some interesting resources that led me to adjust my Notices classes (my implementation of the Signals concept) to expose what I am calling a ‘Future‘; essentially a single-dispatch Signal/Notice, such that if you bind to it post-dispatch, the bound method is immediately called with the data that was originally dispatched.

Last Thought

I am keen to emphasise that these ideas are not complete; they need refining, tweaking and using. Perhaps I have gone down another blind-alley? Perhaps the Processes idea is better after-all? Or perhaps I’m misunderstanding something fundamental about how to wire-up applications with asynchronous functionality that you can enlighten me about?

A blog is for nothing if not shared learning. If you have any comments (positive or negative) then I would really appreciate hearing them!

I have several reasons for choosing not to use Greensock libraries for tweening:

• I have great respect for TweenLite, but I have rarely used it in anger. Most of the time, the applications that I work on have some element of pay-to-play, and Greensock has an unusual license that has put-off at least two employers from using it. I do not want to learn a library that I can only use on some of my projects;
• For all the clean code we try to write, Tweening libraries often jar with their funky APIs. I didn’t want my tweening library to be a statically-referenced black-box of almost unreadable code, I wanted it to have elements with well-defined responsibilities, objects that encapsulate concepts of time, tweens and eases. I wanted to be able to TDD these elements and offer my tests for public scrutiny. In short, I wanted my tweening library to feel more like the rest of my code and less like dark magic;
• Probably most of all, I wanted to write it because I could, and because I hadn’t yet.

Speed and Memory

In the tests that I have done so far, gaia-tween is fractionally behind TweenLite on speed. However, it is ahead in memory consumption! Currently the strategy for gaia-tween is to instantiate the elements that it needs and pool them indefinitely, so there is no garbage collection taking place, but I am looking to add that in as a future iteration. During tweening, no object is constructed nor destroyed by the tweening engine. Compare the memory profile of the two tween engines, from the SpeedDemo test below (SpeedDemo source here):

gaia-tween memory graph

TweenLite memory graph

gaia-tween uses considerably less memory to run than TweenLite.

Structure

The API challenge was to find the right separation of responsibilities to keep the tween engine extensible without the extender having to do unnecessary work. The key features of this API are:

• Time is an independent concept from the tweening engine. A Time object is passed into the Tweening engine, which responds to changes in milliseconds-elapsed appropriately;
• The ease functions have been simplified so that eases take one parameter – a proportion between 0 and 1, and return back a proportion between 0 and 1. This should make it easier for custom eases to be implemented;
• The duration of a tween, the delay before starting it and any ease that may be applied to it are defined at the moment that a tween is added;
• All other definition depends upon the context of the tween, and can be defined in a TweenForm. Currently three different kinds of TweenForms exist: a PropertyTweenForm for performing classic property tweens on objects; a ColorTweenForm for tweening the ColorTranform.color property of a DisplayObject; a MethodTweenForm for defining a method that will take the proportion between 0 and 1.

This diagram may help explain the concepts more easily:

I have also added a convenience class that does the job of creating the TweenForms for you, GaiaTweens.as. This object-pools property tween forms and exposes a simplified API for those who want their tweening engine to keep everything under the hood.

Examples

The ColorTweenForm in action (roll-over to trigger):

By passing in a different Time class, timeline animations are possible:

Some issues with time-lining remain, and will be worked on for future improvements to the engine.

Notices and Signals

I am a huge proponent of the as3-signals library. When Robert Penner originally introduced Signals, I was working on something similar with my friend Simone. Since that time I have used Signals in almost every project I have worked on. However, One thing I really want to be able to do is to define a signal that only exposes an addOnce method. I have advocated this but there is clearly a disagreement about the direction that signals should take. So, I have created my own – simplified – implementation of signals. For want of a better name, I’ve called them Notices. However, if you are interested in using or trying-out gaia-tween but are committed to using Signals, there is a signals branch that replaces the Notices with Signals.

Feedback

I have produced this for my work at Gaia Interactive, but Gaia have agreed to it being released because we would greatly appreciate feedback about it so that it can be improved. Please comment on API decisions, code implementations, feature requests, and so on. The more feedback I get, the more likely I can produce a robust, scalable alternative to the Greensock tweening stable. Or of course, you could fork the library and help improve it more directly!

It turns out that recent versions of Firefox run the Flash Player on a separate process that has a timeout of 45 seconds. If the player hangs for that long then the Flash Player will be crashed. That’s fine for people consuming content, but for developers it is not acceptable.

The solution is to modify about:config, and to amend the value of dom.ipc.plugins.timeoutSecs to the number of seconds before a crash is triggered. You can choose -1 for never, or some sufficiently long period of time.

The design FLA

There are lots of different ways to approach putting a list together. For a bunch of different reasons I tend to work by loading SWFs that have no code into a code-base and then adding functionality by composition. In that way, artists can manipulate assets unencumbered by the code, and I can reuse code across an application with multiple swfs in a very easy-to-manage way.

To create my list then, I create an ‘item’ MovieClip, and iterate it vertically or horizontally in a secondary ‘list’ MovieClip. Then, to demarcate the visual limits of the list I apply a mask to it, like this:

Notice that there is at least one, but more often two ‘overflow’ elements defined on the list; that is, list items that don’t actually show up initially. These are used later on when the list has to scroll.

Compositing the FLA into VList

When this swf is loaded into the application, the VList class configures it very straightforwardly, creating a vector of ListItem objects that wrap each item MovieClip.

When this swf is loaded into the application, the ListItem objects that wrap each list-item MovieClips.

In order to separate functionality from the scrolling mechanism (which could be scrolling arrows, a scrollbar, drag-fling functionality, or whatever else), the position of the list is defined by the VList.position property. When this property changes, the list updates its position by doing the following:

• The list container is moved upwards as the position increases;
• As the top list items disappear out of the masked area, they are repositioned to the bottom and reassigned different data;

In this way, no extra visual items need to be constructed or destructed, and as few objects are moved per change of position as possible. It is fast, clean and efficient.

VList Code

The position setter immediately repositions the container clip when a new position is asserted. (The first line merely checks for isNaN(value) in a more efficient way). Then, it checks whether the top-most element visible in the list is the same as it was before. If it is not, then updateItems() is called.

/**
 * baseY is the position that container.y has when _position is 0
 * dy is the distance between the same point on two adjacent ListItems
 * _index retains the integer value of the previous list position
 */
public function set position(value:Number):void
{
	_position = value != value ? 0 : value;
	container.y = baseY - _position * dy;

	var newIndex:int = _position | 0;
	if (_index == newIndex)
		return;

	_index = newIndex;
	updateItems();
}

updateItems() then iterates through all the ListItems, positions them appropriately within the container clip and asserts data into each item

/**
 * items is a Vector of ListItem, one for each MovieClip list item
 * count is the number of ListItems in items
 * _data is the data that differentiates each item
 */
private function updateItems():void
{
	var i:int = count;
	while (i--)
	{
		var n:int = i + _index;
		var item:ListItem = items[n % count];

		item.mc.y = n * dy;
		item.datum = n < dataLength ? _data[n] : null;
	}
}

ListItem will check whether it’s current datum is the same as the one entered, and if it is it will not update the visual component. If the datum does change, then ListItem passes it’s MovieClip into ListDatum.apply(mc:MovieClip) to be updated.

Add A Scrollbar – Job Done

And that’s it really. It needs a few trimmings of course, like a scrollbar or arrows to actually trigger the scrolling. In the example below a scrollbar class is added, and when the scrollbar changes it relays the position back to the list:

This sturcture is fairly simple too, and can be found in the Example class.

	...

	list = new VList(content.list);

	scrollbar = new VScrollbar(content.knob, content.groove);
	scrollbar.reposition.add(onReposition);

	...

	list.data = data;
	scrollbar.setup(4, data.length);
	scrollbar.isVisible = data.length > 4;
}

private function onReposition(value:Number):void
{
	list.position = value;
}

Summary

I am very satisfied with this implementation. It might need a tweak here or there, but it does it’s job very cleanly. There are more complex cases where you have could have list data of different sizes, or you could have an absolutely enormous data set. Then, this list may not be appropriate, but for the 99% of cases where this is not the case, I think this serves its purpose well.

The complex problem facing most people making lists is choosing which control functionality to implement: drag-fling, scrollbars, little Apple dots, or arrows. Maybe you also want to add touches like bounce effects when you hit the limits of the list. All of these solutions can be developed separately from the core list class and coupled together in a way similar to my basic VScrollbar.

As ever, this code is available on GitHub. I would welcome any comments, improvements or suggestions.

Where does it come from? Clearly it’s built into the Flash Player, but what may be surprising is that when it displays, it is actually added to the stage. It doesn’t float above the stage, it is added to the stage. This is no big deal… usually.

To consider when it might be a problem, try hitting the fullscreen button then hitting the draw button in the demo below. (Depending on the size of your screen, mouse skills will probably be required!)

One of the problems with adding the display to the stage is that it sits in a different security domain to your application. If your application attempts to reference the stage, for example to draw the stage into a BitmapData, then you get hit with a Security sandbox violation. Of course, if your mouse skills weren’t up to it and the element had removed itself from the stage, the error would not occur.

Now, there is probably no good reasons why you should ever need to take draw a copy of the stage, and in fact I found this error because I had (or maybe a colleague had?) done it when I wanted to draw a copy of a particular element. However, since screen-wipe transitions and other effects could easily be implemented in such a way (and since their implementation usually precedes implementing a fullscreen button), the potential for this error does exist.

It doesn’t look like anyone has noticed this error before. I searched for https://www.macromedia.com/support/flashplayer/sys/ in JIRA and Google and didn’t find anything useful. I present it here in the hope that at least one other person won’t be skewered on this AS3 Gotcha like me!

ps. I took some liberties with the code as displayed in the demo above. For full disclosure, view the real source code on GitHub.

If you would like the code, I have put the Scribble.as source code up on GitHub as a gist. It won’t do you the whole demo, but it’ll give you the idea.

Invalidation is a pattern employed to solve problems where updating a model’s data may happen multiple times per frame, but updating the view’s rendering should happen only once. When dependencies exist between multiple models this can get complicated and potentially messy. This article looks at a solution to this mess by unifying invalidation logic into a single manager class.

The purpose of this discussion is not to offer a new class for people to take and use in their libraries so much, though you are welcome, if you should want to. Rather it is to discus a problem and my solution. Hopefully some people will learn something from reading it, and hopefully I will learn something by getting feedback about it!

The Invalidation Pattern

Consider the following simple implementation for drawing a coloured circle:

public class Circle extends Sprite
{

	private var _color:uint;
	private var _radius:Number;

	public function get color():Number { return _color; }
	public function set color(value:Number):void
	{
		_color = value;
		resolve();
	}

	public function get radius():Number { return _radius; }
	public function set radius(value:Number):void
	{
		_radius = value;
		resolve();
	}

	private function resolve():void
	{
		graphics.clear();
		graphics.beginFill(_color);
		graphics.drawCircle(0, 0, _radius);
		graphics.endFill();
	}

}

The problem here is that if in one frame I changed both the radius and the color, the resolve() function would be called twice. Though not a problem in this case, it could be if the resolve() function involved a lot of complex logic.

The invalidation pattern resolves it this way:

public class Circle extends Sprite
{

	private var _color:uint;
	private var _radius:Number;

	public function get color():Number { return _color; }
	public function set color(value:Number):void
	{
		_color = value;
		invalidate();
	}

	public function get radius():Number { return _radius; }
	public function set radius(value:Number):void
	{
		_radius = value;
		invalidate();
	}

	public function invalidate():void
	{
		... at some future point of my choosing, trigger resolve() ...
	}

	public function resolve():void
	{
		graphics.clear();
		graphics.beginFill(_color);
		graphics.drawCircle(0, 0, _radius);
		graphics.endFill();
	}

}

Often in AS3, the invalidate() function looks like this:

public function invalidate():void
{
	addEventListener(Event.ENTER_FRAME, onEnterFrame);
}

private function onEnterFrame(event:Event):void
{
	removeEventListener(Event.ENTER_FRAME, onEnterFrame);
	resolve();
}

It is a good pattern that solves the problem of multiple resolve() calls. The actual mechanism contained inside invalidate() which causes resolve() to be called once at a convenient point is unimportant. For this sort of structure, this simple implementation does the job.

Where The Invalidation Pattern Becomes Complicated

Imagine that you have two classes: a line, and a circle, the intersection of which defines two circular segments. In fact, don’t imagine: look at this:

Both the line and circle implementations consist of two points which, on moving, invalidate the their equations. On resolve() the equations are resolved. The segments depend upon the the line and circle; when the line or circle is invalidated, they should be invalidated also.

A mechanism for the segments to know when their definiens (that which defines them) are resolved is required, suggesting that each element conforms to a common interface:

public interface Invalidates
{

	function invalidate():void;

	function get invalidated():Signal;

	function resolve():void;

}

and an implementation along these lines:

public class Line implements Invalidates
{

	private var _ax:Number;
	private var _ay:Number;
	private var _bx:Number;
	private var _by:Number;

	private var _invalidated:Signal;

	public function Line()
	{
		_invalidated = new Signal(Invalidates);
	}

	public function get ax():Number { return _ax; }
	public function set ax(value:Number):void
	{
		_ax = value;
		invalidate();
	}

	... missing a few uninteresting methods ...

	public function invalidate():void
	{
		_invalidated.dispatch(this);
	}

	public function resolve():void
	{
		... resolve the line ...
	}

}

public class Segment implements Invalidates
{
	private var _line:Line;
	private var _circle:Circle;

	... missing the constructor ...

	public function get line():Line { return _line; }
	public function set line(value:Line):void
	{
		_line = line;
		_line.invalidated.add(onInvalidated);
	}

	... missing a few uninteresting methods ...

	private function onInvalidated(definien:Invalidates):void
	{
		invalidate();
	}

	public function resolve():void
	{
		_line.resolve();
		_circle.resolve();

		... the rest of the resolution ...
	}
}

The problem here is the same problem that led us to consider the Invalidation Pattern in the first place: namely, that the Line’s resolve() method is going to get called a lot. Sure, we can pack the methods with lots if calls like:

private function invalidate():void
{
	if (_isInvalidated)
		return;

	_isInvalidated = true;
	invalidate();
}

public function resolve():void
{
	if (!_isInvalidated)
		return;

	_isInvaldiated = false;
	_line.resolve();
	_circle.resolve();

	... the rest of the resolution ...
}

However, it starts to feel like the classes are consumed with handling the invalidation management, rather than with what should be their single responsibility of properly modelling the geometrical entities for which they are named.

An important feature of this implemenation is that it guarantees that the Line’s and Circle’s resolve() methods are called before the sgement resolves. If B depends on A, then A must resolve before B resolves. This is a key feature of the Invalidation Manager, below.

Managing Invalidation

The current as3geometry library attempts to solve the problem of invalidation using the InvalidationManager.as class.

The Invalidation Manager handles classes that satisfy the Invalidates.as interface. Invalidates objects can be registered to the InvalidationManager, and dependencies can be established. As this happens, objects are categorized into tiers.

Initially, since every object is independent of each other when registered, newly registered elements are considered in tier 0. However, if a dependency is established such that B depends on A, B is put into the tier above A, so if A is in tier 0, B is in tier 1. If then C depends on B, since B is already in tier 1, C goes into tier 2.

The utility of the tiers comes from the fact that all objects in tier 0 are independent of each other and may be resolved in any order. Tiers are resolve in ascending order, ensuring that any object that is depended upon is resolved before any object which depends on it.

The problem with this approach comes when, for example, A depends on B depends on C already so they have the following tiers:

Then, if I have another object D already in tier 3, and define that B depends on D, I must move B to tier 4 and therefore also move C to tier 5.

Circularity presents an interesting problem within this system. If A depends on B depends on C, and then I define that C depends on A, the tier system breaks down. Currently attempting to create a circular reference will fail and an error will be thrown.

In order to keep the InvalidationManager clean, it does not actually handle when it resolves, but instead dispatches a signal when it has elements that require resolution. In the as3geometry implementation the AS3GeometryContext.as wraps the InvalidationManager and hooks it to the player events to so that when invalidation occurs it is resolved in good time.

The Invalidates classes, other than telling the contxt what it has a relationship to and what it does not, no longer contains any code that tries to manage other objects’ invalidations:

public class Line implements Invalidates
{

	private var _ax:Number;
	private var _ay:Number;
	private var _bx:Number;
	private var _by:Number;

	private var _context:InvalidationManagerContext;
	private var _invalidated:Signal;

	public function Line(context:InvalidationManagerContext)
	{
		_invalidated = new Signal(Invalidates);

		// elements that don't depend on other classes  like this don't really need the
		// context stored, but I store it here for consistency, and in case the structure
		// changes
		_context = context;
		context.register(this);
	}

	public function get ax():Number { return _ax; }
	public function set ax(value:Number):void
	{
		_ax = value;
		invalidate();
	}

	... missing a few uninteresting methods ...

	public function invalidate():void
	{
		_invalidated.dispatch(this);
	}

	public function resolve():void
	{
		... resolve the line ...
	}

}

public class Segment implements Invalidates
{
	private var _line:Line;
	private var _circle:Circle;

	private var _context:InvalidationManagerContext;
	private var _invalidated:Signal;

	public function Segment(context:InvalidationManagerContext)
	{
		_invalidated = new Signal(Invalidates);

		_context = context;
		_context.register(this);
	}

	public function get line():Line { return _line; }
	public function set line(value:Line):void
	{
		_line = line;
		_context.addDependency(_line, this);
	}

	... missing a few uninteresting methods ...

	private function onInvalidated(definien:Invalidates):void
	{
		invalidate();
	}

	public function resolve():void
	{
		... just resolve here! this is the big win ...
	}
}

Conclusion

A benefit to this approach is that Invalidates classes need very little boiler-plate code. The author of an Invalidates class need know only that changes should call invalidate() and that all resolution logic happens in resolve(). Responsibilities are extremely well separated.

The as3geometry implementation wraps the InvalidationManager into an AS3GeometryContext.as class that has a little more logic than the InvalidationManager, which does not have a mechanism for actually triggering the mass resolution. While the InvalidationManager handles the internal logic set-out above, the AS3GeometryContext handles hooking up the InvalidationManager to the player events.

There is a downside, of course. Currently in as3geometry, the constructor of every class contains a reference to the AS3GeometryContext, and every class stores a reference to it. It is not clear to me that this approach is avoidable, unless the manager is defined as a singleton. There are lots of good reasons why singletons are bad, not least because I might have good reason to have two parallel geometric contexts in one application.

The parabola is defined by the directrix AB and the focus C

It was apparent from the diagram that:

• H is the midpoint of the line segment AC;
• AD is perpendicular to AB, and HD is perpendicular to AC, so D can be calculated as the intersection of these lines;
• J is the midpoint of the line segment BC;
• BE is perpendicular to AB and JE is perpendicular to BC, so E can be calculated as the intersection of these lines;
• K is the intersection of the lines JE and HD, so E can be calculated as the intersection of these lines;
• The parabolic segment defined by the line segment directrix AB and the focus C is also defined by a quadratic bezier curve with the start point D, the end point E and the control point K.

The full calculation (with some different variable names I’m afraid!) was codified in the ParabolaDrawer.as class.

Parabola defined by a line and vertex

Parabola segment defined by a line segment and vertex:

Usefully, a parabola (which, precisely, is “the locus of points equidistant from a point and a line”) can be expressed as a quadratic bezier curve. The implementation ‘simply’ finds the three control points of a quadratic bezier curve and then uses the Flash Player’s Graphics.curveTo method to draw.