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!

RobotLegs is an MVCS framework that aims to decrease inter-dependency between different parts of code, so that code is more robust, and more reusable. It does this through a combination of dependency injection and the model-view-controller (+services) design pattern. The ‘controller’ portion of RobotLegs’ MVCS implementation is achieved by offering coders a simple way of implementing the Command pattern and binding commands to events that can be called from other areas of the code.

Problematically, commands are stateless and synchronous. They are not wired up to handle asynchronicity under-the-hood. “Async Commands” amend the Command structure to attempt to solve this problem, but they still contain architectural limitations that force us to restrict the way we code to the potential of the framework. Using Commands for asynchronous processes often require us to ‘double wire’ between different application elements to solve the problem of passing data between classes.

What I am calling Processes are a redesign of the Async Command concept that seek to resolve these issues. They can be used in parallel with Commands to elegantly handle the problems of asynchronous code in RobotLegs.

The Async Pattern

The event model exists explicitly because we often need to wire up code to be triggered at an indeterminate future event. Fundamentally, client-side programming is about state and asynchronicity: events handle the asynchronicity. We handle them with this sort of pattern:

public function init():void
{
	var process:AsyncProcess = new MyAsyncProcess();
	process.addEventListener(AsyncProcessEvent.COMPLETE, onProcessComplete);
	process.init();
}

private function onProcessComplete(event:AsyncProcessEvent):void
{
	var processs:AsyncProcess = event.process;
	process.removeEventListener(AsyncProcessEvent.COMPLETE, onProcessComplete);

	parse(process.data);
}

Signals improves upon this structure by removing the necessity of event classes and offers some added features like automatically handling the removal of listener functions:

public function init():void
{
	var process:AsyncProcess = new MyAsyncProcess();
	process.completed.addOnce(onProcessComplete);
	process.init();
}

private function onProcessComplete(process:AsyncProcess):void
{
	parse(process.data);
}

This pattern is simple but powerful – create an object to tokenise or act-as-delegate-to the process, bind to some generic event/signal defined on the token, then initialise the process. I take the signal implementation to be a substantial improvement to the original.

The Async Pattern across different objects

A more complex case emerges if one class wants to launch a process in another class and retrieve data from its result. Ideally we want to keep the same three-step process.

class Model
{
	public var service:Service;

	public function init():void
	{
		service.completed.addOnce(onServiceComplete);
		service.init();
	}

	private function onServiceComplete(process:AsyncProcess):void
	{
		parse(process.data);
	}
}

interface Service
{
	function get completed:Signal;

	function init():void;
}

Unfortunately, this pattern is now insufficient, because it is possible for two different objects to trigger an asynchronous process from the same service at overlapping times (such that the second one is triggered before the first response).

class InitModelsCommand
{
	public var a:Model;
	public var b:Model;

	public function execute():void
	{
		a.init();
		b.init();
	}
}

In this scenario, if modelA and modelB both call init() in turn, then modelB will receive the data for modelA, then remove its listener before its own data is retrieved (assuming that modelA’s data is returned first, otherwise vice-versa).

This problem comes about because the service exposes a single Signal for multiple requests. There are two options to remedy this limitation:

// option A - the calling service tells the response where to go
interface Service
{
	function init(signal:Signal):void;
}

// option B - the service generates a response signal on a per-call basis
interface Service
{
	function init():Signal;
}

There’s not a lot between the two solutions, but I prefer Option B because it keeps together the repsonsibilities for creating and managing delegates to the asynchronous process in the same place as the process itself.

The pattern morphs to this:

class Model
{
	public var service:Service;

	public function init():void
	{
		service.init().addOnce(onServiceComplete);
	}

	private function onServiceComplete(process:AsyncProcess):void
	{
		parse(process.data);
	}
}

interface Service
{
	function init():Signal;
}

Here, be aware that if the signal responds within the init() method then it will not be routed to onServiceComplete. This can be handled by defining a signal that once dispatched, will dispatch immediately to any methods that are then added.

Asynchronous Processes in RobotLegs

The point of RobotLegs is to keep as few dependencies between different parts of code as possible. Ideally a model and a service shouldn’t reference each other, so RobotLegs best-practises would suggest you separate their interaction into a Command:

class InitModelCommand
{
	[Inject]
	public var model:Model;

	[Inject]
	public var service:Service;

	public function execute():void
	{
		service.completed.addOnce(onResponse);
		service.init();

		commandMap.detain(this) // if we don't do this for an async command everything could explode
	}

	private function onResponse(process:AsyncProcess):void
	{
		commandMap.release(this) // if we don't do this for an async command commands stay in memory

		model.parse(process.data);
	}
}

There several problems with this implementation. Imagine that this command is called as part of an initialisation routine, and once complete, another command should be called:

class Context
{
	public function onStartup():void
	{
		signalCommandMap.mapCommand(InitModel, InitModelCommand);
		signalCommandMap.mapCommand(InitView, InitViewCommand);
	}
}

How should InitViewCommand be called? The only place where the InitModelCommand is known to be complete is in its own onResponse command:

class InitModelCommand
{
	[Inject]
	public var initView:InitView;

	...

	private function onResponse(process:AsyncProcess):void
	{
		model.parse(process.data);
		initView.dispatch();
	}
}

This is unsatisfactory. Without this, the command is neatly encapsulated and simple to describe and understand. Once this code is added, the command takes on two responsibilities: firstly to initialise the model, and secondarily to kick-off the InitViewCommand.

The stateless command design pattern is ill-suited for asynchronous processes, and the attempt to use them leads to poor code design.

An asynchronous process for RobotLegs

The simple cases at the start of this article are instructive if we try to design a preferred architecture from the ground up. While retaining the power of RobotLegs to remove class dependencies, we want to find a way to use the simple asynchronous process pattern to wire up processes.

These design considerations have led me to what I’ve tentatively called the robotlegs-async-process-extension. It’s very early stages, and as usual I’m sharing the code more to get feedback than as a polished piece of work, but it functions to provide what I think is a superior alternative to Async Commands.

The structure is roughly like this:

class Context
{
	public function onStartup():void
	{
		// a delegate is a new concept...
		processMap.map(InitModelDelegate, InitModelProcess);
		processMap.map(InitViewDelegate, InitViewProcess);
	}
}

Class InitModelDelegate extends ProcessDelegate {}

Class InitViewDelegate extends ProcessDelegate {}

class InitProcess extends Process
{
	[Inject]
	public var initModel:InitModelDelegate;

	[Inject]
	public var initView:InitViewDelegate;

	public function execute():void
	{
		initModel.execute().addOnce(onModelInited);
	}

	private function onModelInited():void
	{
		initView.execute().addOnce(onViewInited);
	}

	private function onViewInited():void
	{
		complete();
	}
}

Note the features here:

• Like the SignalCommandMap extension, a different core structure, the ProcessMap is defined that allows Processes to be defined in a way similar to Commands;
• Rather than binding an event or signal to a Process, we bind a ProcessDelegate. We need a little bit of extra functionality in the ProcessDelegate for the structure to work satisfactorily, but this is not functionally different from the SignalCommandMap extension;
• When a delegate is executed, it passes back a signal that the calling object binds to in order to know when the process completes (it may also send back data through this callback);
• Processes can’t be duck-typed, because they also need to inherit the functionality from their base class Process. Process exposes a complete() method that is called when the Process completes. If complete() is called inside execute(), then the Process becomes functionally equivalent to a Command.

In fact, this is not quite the library as developed, because I have started using Notices rather than Signals, so I have ported this across to Signals since it has a much broader adoption. Notices are pared down, simple implementations of Signals that allow you to expose very simple interfaces like the SingularNotice interface. It’s a preference thing; if anyone would like the original implementation with Notices, I’m happy to publish it.

I hope that this gives you some food for thought with respect to asynchronous processes. I’d love to know what you think about the idea, the implementation, the implied critique of RobotLegs. Let me know!

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!

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.

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.

Back to work, and I was doing a little prototyping this evening, when I came across a familiar problem: In AS3 we can use

[Embed(source="asset.swf", symbol="symbol")]
private var symbolClass:Class;

var symbol:MovieClip = new symbolClass();

to embed a symbol from an art SWF in what is probably a code-built SWF. That’s great, but what if you want to embed an entire SWF?

[Embed(source="asset.swf")]
private var assetClass:Class;

var asset:MovieClip = new assetClass();

looks like it should do the trick, but you can’t access any of the information within the asset. That’s a real pain, the reason for which is pretty convoluted. I remembered working around this problem in the past, and happily managed to unearth a long-forgotten treasure in my codebase, which I thought I’d share (having rapidly refactored it to use as3-signals, naturally).

package com.alecmce.util
{
	import org.osflash.signals.Signal;

	import mx.core.MovieClipAsset;

	import flash.display.Loader;
	import flash.display.LoaderInfo;
	import flash.display.MovieClip;
	import flash.events.Event;

	public class UnpackEmbed
	{
		private var _ready:Signal;

		private var _asset:MovieClipAsset;
		private var _content:MovieClip;

		public function UnpackEmbed(assetClass:Class)
		{
			_asset = new assetClass();
			_ready = new Signal(UnpackEmbed);

			var loader:Loader = Loader(_asset.getChildAt(0));
			var info:LoaderInfo = loader.contentLoaderInfo;
			info.addEventListener(Event.COMPLETE, onLoadComplete);
		}

		private function onLoadComplete(event:Event):void
		{
			var info:LoaderInfo = LoaderInfo(event.target);
			info.removeEventListener(Event.COMPLETE, onLoadComplete);

			_content = MovieClip(info.loader.content);
			_ready.dispatch(this);
		}

		public function get content():MovieClip
		{
			return _content;
		}

		public function get ready():Signal
		{
			return _ready;
		}

		public function get asset():MovieClipAsset
		{
			return _asset;
		}
	}
}

When you embed a SWF in this way then instantiate it, Flash somehow conspires to create a MovieClipAsset with a Loader inside, which will be ‘loading’ the already-embedded content. The content is not available immediately (it may be sometimes, I have encountered cases where it was not), so you have to wait for an Event.COMPLETE to be fired before you can access it. This class exposes a signal that informs you when the content is ready. It could probably be more rigorous, such as including an isComplete flag, but it serves my purposes, when used in the following manner:

[Embed(source="asset.swf")]
private var assetClass:Class;

asset = new UnpackEmbed(assetClass);
asset.ready.addOnce(onAssetReady);

private function onAssetReady(asset:UnpackEmbed):void
{
	// now we can access the asset.content!
}

RobotLegsPong attempts to combine RobotLegs application framework with the as3signals event model and a Frame-Ticker (as well as a pinch of ASUnit unit-testing) to create a ‘game’.

It is an open-source project, available on GitHub as an example of using RobotLegs together with these other technologies.

Source Code: github/alecmce/RobotLegsPong

RobotLegsPong is not a very good game; it is playable only in the loosest sense. Bats require to be dragged in order to move (and there is no computer-logic to play against), so you could not really play against an opponent. The purpose of the exercise was to see what structure a game like Pong would take within the RobotLegs framework.

The purpose of this article is to describe the particulars of the technologies and why I chose them. In a follow-up article, I will look in more detail how RobotLegsPong is wired up.

Why I Chose These Technologies

RobotLegs

The RobotLegs framework is a lightweight, flexible application framework that allows coders to spend less time wiring up their application, and more time working on its functionality.

Frameworks are often criticised because they force developers to write code in a particular way, which might be inappropriate for a particular context. I have used Cairngorm, Pure MVC, as well as some proprietary frameworks, and have found that all of them do some things well, and do other things clumsily. So far I have not found this problem with RobotLegs, because most of the time it gets out of the way and lets you code; in fact, it does more than that: it reduces the amount of code you have to write.

as3signals

RobotLegs comes with an application event bus, but I have decided to circumvent that and use as3signals instead. as3signals allows you to define an object which acts as an event dispatcher within an application.

I like as3signals because describing an event as a Signal object allows my event model to be described through interfaces. as3signals is supposed to be fast too. Then again, interfaces are slow. The relative speeds of the approaches is interesting, but not a significant factor in my decision making process.

Frame-Ticker

The frame-ticker is a simple idea: rather than creating multiple enter-frame event listeners, each creating event objects, create one enter-frame listener and a main game loop iterating through those methods that need to be called per-iteration.

This implementation came out of a discussion on Twitter that I was involved in on the fringes; I wrote about it in a previous blog post.

ASUnit

Unit testing enables developers to test portions of their code in isolation, so that they can be confident that every method works exactly as the developer intended. They also represent a secondary form of documentation-in-code; if you want to know how I meant a method to work, reading the unit test will tell you almost everything you need to know (including, if a good test is missing, what I didn’t consider).

That said, I have not unit tested every method; in this example I have only unit-tested the geometric logic for the bats. This is bad practice, however under time constraints I think that it is most important to unit test what is complex, mathematical or ambiguous, since this is where behaviour is most likely to fall down.

[Inject]

The ‘trick’ to using RobotLegs is that you do not need to inject dependent objects into classes when you contruct them; this is done automatically. This code:

public class Dependee {}

public class MyExample
{
	public var dependee:Dependee;

	public function MyExample(dependee:Dependee)
	{
		this.dependee = dependee;
	}
}

becomes this code:

public class Dependee {}

public class MyExample
{
	[Inject]
	public var dependee:Dependee;
}

The metadata tag [Inject] has the effect of automatically injecting the dependee into the class when it is constructed. This isn’t much on the face of it, but it is enough. It feels to me as though a quarter of my code is actually just wiring up classes so that they each have access to the classes that they need to function, or passing objects around methods. The [Inject] tag lets me shift all of that wiring into the RobotLegs framework.

Context

There is a little more to the RobotLegs story however; how should RobotLegs react when it comes across an [Inject] tag? It could construct a new Dependee object, or it could be that I want only one Dependee object to be injected wherever the [Inject] tag is found. This is where the Context class becomes meaningful.

In the PongContext, different classes are wired up in different ways. Their definitions are defined by adding injector mappings and the mediatorMap mappings in the startup method.

public class PongContext extends Context
{
	override public function startup():void
	{
		...
		injector.mapSingleton(DragMechanism);
		injector.mapSingletonOf(Geometry, GeometryModel);
		injector.mapClass(BatGeometry, BatGeometryModel);
		...
	}
}

injector.mapSingleton

injector.mapSingleton(DragMechanism)

mapSingleton indicates that only one instance of the class entered should be constructed. In this case, just one DragMechanism will be created, and injected whenever this is found:

[Inject]
public var mechanism:DragMechanism;

injector.mapSingletonOf

injector.mapSingletonOf(Geometry, GeometryModel);

mapSingletonOf extends the mapSingleton idea to interfaces and their implementing classes. In this case the Geometry interface is mapped to the GeometryModel class. The injection is called as follows:

[Inject]
public var model:Geometry;

No reference to the GeometryModel is needed in any class other than the PongContext. This allows a very pure use of interfaces across the application.

injector.mapClass

injector.mapClass(BatGeometry, BatGeometryModel)

injector.mapClass works a little differently; whenever a BatGeometry interface is flagged to be injected, a new instance of BatGeometryModel is constructed and injected into the class, so the following code is used to create the injection:

Each BatMediator needs its own BatGeometry object. By using the mapClass method, multiple BatGeometryModel objects will be constructed, one for each time the following code is found:

[Inject]
public var model:BatGeometry;

Mediators and Components

public class PongContext extends Context
{
	override public function startup():void
	{
		...
		mediatorMap.mapView(Background, BackgroundMediator);

		addChild(new Background());
	}
}

mediatorMap references a slightly different aspect of the application: your view objects. The mediatorMap allows users to define associations between display objects and Mediators. These two parts comprise the View aspect of the standard MVC pattern.

The DisplayObject – in this case Background – is the asset that you want to be visible on the stage. In my pong example this is essentially just a Sprite, though it might just as well have been imported as a graphical asset in a SWC.

The Mediator is associated with the DisplayObject so that when an instance of the DisplayObject is created, the corresponding Mediator is also constructed. The BackgroundMediator looks something like this:

public class BackgroundMediator extends Mediator
{
	[Inject]
	public var view:Background;

	override public function onRegister():void
	{
		...
	}
}

The DisplayObject Background is injected into the BackgroundMediator when it is constructed. The DisplayObject can then be manipulated. It is an elegant solution that separates display object from UI logic.

addChild(new Background());

is all that is needed to wire the entire DisplayObject/Mediator combination.

RobotLegs & Tickers

The RobotLegs structure is particularly useful for wiring up a Ticker-based application because one ticker can be mapped as a singleton, and injected to all those methods that need to iterate every frame:

public class PongContext extends Context
{
	override public function startup():void
	{
		...
		injector.mapSingletonOf(Ticker, EnterFrameTicker);
		...
	}
}

RobotLegs with as3signals

I really like the style of event dispatching that as3signals provides, but my implementation demands that if one class requires another class then it must flag it to be injected, and then the signal wired up in a method flagged as [PostConstruct] (see GeometryModel). This doesn’t feel like the right solution.

Integrating as3signals with RobotLegs is beyond the scope of this article. It looks like Joel Hooks and Robert Penner are making inroads into this problem through as3signals’ Google Group. I look forward to seeing what they come up with.