There has been a lot of people who played with Away3D and built awesome things. A lot of said awesome things were built by people who know, or know someone that knows 3D modeling, which is why the quality has been so awesome. However, it may not always be necessary to build a full 3D world, sometimes a project may simply require some 3D elements over a 2D background. But how do you place an image behind all sorts of 3D objects if Away3D's View3D has a black background? I will try and explain the process in this article. Warning: matrices and trigonometry ahead!

Build it and they will come

Usually, if you want to place an image and make it fit your document dimensions, you simply stretch the image accordingly. In 3D however, it is not as simple, as the world dimensions are not necessarily measured in pixels. While working with the guys from Float4, I came to understand that meters are oftentimes used as measurement unit. With that in mind, we cannot directly use the dimensions of our document.

So let's say we want to place an image in the 3D world and make it fill the viewport (the visual space taken by Away3D). At first, we would need an image, and a plane onto which we would like to place the image. As I wrote previously, materials applied onto shapes need to be in dimensions that are a power of 2, so will will need to rescale our image. A Matrix will fulfill this need.

private const WIDTH:uint = 640;
private const HEIGHT:uint = 640;
private const MATERIAL_WIDTH:uint = 1024;
private const MATERIAL_HEIGHT:uint = 1024;
 
[Embed(source="assets/images/escher-relativity.png")]
private const EscherImageClass:Class;
 
private var _imageData:BitmapData;
private var _matrix:Matrix;
private var _material:BitmapMaterial;
private var _plane:Plane;
private var _view3D:View3D;

WIDTH and HEIGHT represent the dimensions of my document, and also the dimensions of the image. The MATERIAL_WIDTH and MATERIAL_HEIGHT represent the dimensions needed for the material, dimensions that are a power of two. Here I will be using an image from Escher, obtained from Wikipedia. There is no need for a Bitmap per se, but we will need the image's BitmapData, hence the _imageData variable.

Let's do this!

Normally, I resize the material dimensions to a value higher than what I need to display; first the material is stretched up, and then visually fitted to the original dimensions of the image. If we were to scale the material to smaller dimensions than that of the image, the plane would stretch up the material afterwards when displaying the image, resulting in possible loss of smoothness or detail.

_matrix = new Matrix();
_matrix.scale(MATERIAL_WIDTH / WIDTH, MATERIAL_HEIGHT / HEIGHT);

Let's draw an instance of the Escher image into the_imageData. This is where _matrix comes in handy. I wonder what pushed Adobe's engineers to make an architectural choice where they thought users would use a ColorTransform, a BlendMode or a clipping Rectangle more often than a flag to smooth the drawing. I mean, putting the flag as a last argument? Anywho, let's add a lot of null parameters...

_imageData = new BitmapData(MATERIAL_WIDTH, MATERIAL_HEIGHT);
_imageData.draw(new EscherImageClass(), _matrix, null, null, null, true);

Next, create the material. As seen previously, let's use a simple trick to assign whether or not the material is mipmapped.

_material = new BitmapMaterial(_imageData, true);
_material.mipmap = (_imageData.width == _imageData.height);

Apply the material to the plane, add the plane to the View3D, and then add the view to the display list.

_plane = new Plane(_material);
_view3D = new View3D();
_view3D.scene.addChild(_plane);
addChild(_view3D);

Do not forget to listen to Event.ENTER_FRAME and call the View3D.render() method at every update.

addEventListener(Event.ENTER_FRAME, updateHandler);

Run it, and what do we get?...

Nothing.

Uh?

By default, the plane is added at (0, 0, 0), so it should be visible...

It is, it turns out that an API choice—which may make sense in a 3D world, but that I do not understand—puts the plane with its face up on instantiation. What this means is when it is created, we see its side, which has no thickness. Just change the yUp parameter to false, so the new plane will then face the camera upon creation.

_plane.yUp = false;

We should get something like this.

If we compare the image and this result, we notice that the image's edges are cropped, which means the plane is too close. Below is a diagram explaining this visually.

Imagine a pyramid drawn from the camera at its top with an angle that is the camera's field of view, up until a certain point. From the camera's point of view, there is always a certain frame that is visible, that is the viewport. However, that pyramid is not infinite, actually what the camera sees is not even a pyramid. The viewing frustum, what is visible within a 3D world, is an area from a certain threshold (the near plane) to another one (the far plane), that's what is visible within a 3D world. What happens with the code above is that the plane is bigger than the frustum, thus being cut.

Below is what we want to achieve:

SOH-CAH-TOA

This is where the fun begins! How do we fit our plane into our viewport? It is possible to simply move the plane on the z axis and eventually position the plane properly to fit our need. But what if the dimensions change? We'd be back onto square one. This problem requires good ol' trigonometry, and the pythagorean theorem.

You may wonder what this title means. It's a mnemonic trick that's been given to me back in high school on how to remember the rules of trigonometry:

Sine of an angle = Opposite side / Hypothenuse

Cosine of an angle = Adjacent side / Hypothenuse

Tangent of an angle = Opposite side / Adjacent side

Then let's consider this as a trigonometry problem, illustrated below. We have a camera, the Camera3D, which is located at (0, 0, -500) by default. Look at the sources to confirm, it is the case with Away3D, but it may be different in other 3D engines. We have a plane with a position yet undefined, but we do want to make sure that its fits perfectly into the viewport.

Where does that 60° angle in the illustration above come from? If we take a look at the Camera3D constructor, we find that it uses a PerspectiveLens by default. In that lens constructor, we can see the default field of view is 60, which is in degrees. It's too bad we need to look at the source to obtain this, it would have been simpler to use a getter to be able to check it, but there is none.

Good, we have an angle, we can calculate dimensions and positions. Let's set an arbitrary z for the plane, we'll see further that it doesn't matter.

var angleY:Number = 60;
var cameraZ:int = _view3D.camera.z;
var planeZ:int = 500;
var distFromCamToPlane:Number = Math.abs(cameraZ) + planeZ;

Since the field of view is vertical, let's measure the height of our plane first. Let's not forget that the field of view covers the whole height, but in order to work with rectangle triangles, we will use only half of that angle. We know the angle, we know the distance from the camera to the plane (the adjacent side), but we do not know the opposite side, so let's use the tangent. The Math.tan() takes radians, so just make sure to convert those degrees to radians.

var planeHeight:int = Math.tan((Math.PI / 180) * (angleY * 0.5)) * distFromCamToPlane;

Since this represents only half of the height, let's correct it for what we need further.

planeHeight *= 2;

To obtain the width of our plane, simply apply the aspect ratio of the image. In this case the image is a square, but it may very well be any kind of rectangle.

var aspectRatio:Number = WIDTH / HEIGHT;
var planeWidth:int = planeHeight * aspectRatio;

And now we are ready to create our plane with the proper dimensions and position.

_plane = new Plane(_material, planeWidth, planeHeight);
_plane.yUp = false;
_plane.z = planeZ;

Let's take a look at the whole process at once.

// get the scale to apply to the image
_matrix = new Matrix();
_matrix.scale(MATERIAL_WIDTH / WIDTH, MATERIAL_HEIGHT / HEIGHT);
 
// create the image data
_imageData = new BitmapData(MATERIAL_WIDTH, MATERIAL_HEIGHT);
_imageData.draw(new EscherImageClass(), _matrix, null, null, null, true);
 
// create the material
_material = new BitmapMaterial(_imageData, true);
_material.mipmap = (_imageData.width == _imageData.height);
 
// create the view
_view3D = new View3D();
 
// camera values
// see away3d.camerasCamera3D's default lens' field of view
// in away3d.cameras.lenses.PerspectiveLens
// it turns out that the field of view is vertical
var angleY:Number = 60;
var cameraZ:int = _view3D.camera.z;
 
// this position is arbitrary as we will see further
// useful to calculate the distance between the camera and the plane
var planeZ:int = 500;
var distFromCamToPlane:Number = Math.abs(cameraZ) + planeZ;
 
// since the field of view is a vertical angle, calculate the height of the plane first
// use pythagorean theorem to calculate
// tip for trigonometry: soh-cah-toa
// toa: tan(angle) = oppositeSide / adjacentSide
var planeHeight:int = Math.tan((Math.PI / 180) * (angleY * 0.5)) * distFromCamToPlane;
 
// and since it was for a rectangle triangle, thus half the size, double the length
planeHeight *= 2;
 
// useful for resizing the image
var aspectRatio:Number = WIDTH / HEIGHT;
 
// use the aspect ratio to calulcate the width of the plane
var planeWidth:int = planeHeight * aspectRatio;
 
// create the plane
_plane = new Plane(_material, planeWidth, planeHeight);
_plane.yUp = false;
_plane.z = planeZ;
 
// add 3D objects to the scene
_view3D.scene.addChild(_plane);
 
// add the away3d view to the display list
addChild(_view3D);
 
// listen to the updates
addEventListener(Event.ENTER_FRAME, updateHandler);

This should produce a result like this, where the image fits perfectly in the viewport.

For additional fun, I added an option to click to rotate it, so that it demonstrates that it is indeed 3D.

Sources

As I always do in my tutorials, you can download the sources. This project has been built for Flash Player 11+ with FDT. You may need to adapt the Flex SDK.

Enjoy!

Now that your environment is set up to play with Away3D, let's create something! In my previous post, I concluded that you can now experiment, and so I did too. It turned out that there are some little intricacies about putting a simple image on a simple cube. Let's take a look.

Create a cube

This part has got to be the simplest, thanks to the nice API that the guys from Away3D built.

ActionScript 3.0:

package
{
import away3d.containers.View3D;
import away3d.materials.ColorMaterial;
import away3d.primitives.Cube;
 
import flash.display.Sprite;
import flash.display.StageAlign;
import flash.display.StageScaleMode;
import flash.events.Event;
 
[SWF(frameRate="60", backgroundColor="#ffffff", width="640", height="360")]
public class Main extends Sprite
{
	// + ----------------------------------------
	//		[ VARS ]
	// + ----------------------------------------
 
	private	var	_view3D		:View3D;
	private	var	_cube		:Cube;
 
	// + ----------------------------------------
	//		[ CONSTRUCTOR ]
	// + ----------------------------------------
 
	public function Main()
	{
		super();
		initStage();
		addEventListener(Event.ADDED_TO_STAGE, addedToStageHandler);
	}
 
	// + ----------------------------------------
	//		[ PRIVATE METHODS ]
	// + ----------------------------------------
 
	private function initStage():void
	{
		stage.align = StageAlign.TOP_LEFT;
		stage.scaleMode = StageScaleMode.NO_SCALE;
	}
 
	private function init():void
	{
		// it is necessary to add a texture to the shape so it is visible
		var material:ColorMaterial = new ColorMaterial(0xffffff);
 
		// I personally prefer to set vars for repetitive values
		var cubeSize:uint = 240;
		_cube = new Cube(material, cubeSize, cubeSize, cubeSize);
 
		// add the 3D elements to the stage
		_view3D = new View3D();
		_view3D.scene.addChild(_cube);
		addChild(_view3D);
 
		// add a listener so it becomes possible to render the 3D world
		addEventListener(Event.ENTER_FRAME, enterFrameHandler);
	}
 
	// + ----------------------------------------
	//		[ PRIVATE METHODS ]
	// + ----------------------------------------
 
	private function addedToStageHandler(event:Event):void
	{
		removeEventListener(Event.ADDED_TO_STAGE, addedToStageHandler);
		init();
	}
 
	private function enterFrameHandler(event:Event):void
	{
		// render the 3D world
		_view3D.render();
	}
}
 
}

With this code, this is what you should get as a result:

Not exactly exciting. For one, a ColorMaterial is really a flat color, so the best way to make it live a bit is adding light elements, which we will not see in this post (and that's also because I have not learned that yet). Also, we only see once face of the cube, quite boring.

To at least view that this object is in 3D, simply update the enterFrameHandler function.

ActionScript 3.0:

private function enterFrameHandler(event:Event):void
{
	// increment the cube's rotation values to see its different sides
	_cube.rotationX++;
	_cube.rotationY++;
	_cube.rotationZ++;
 
	// render the 3D world
	_view3D.render();
}

Apply an image texture

Most probably, you would like to add your own textures to your 3D elements. This is where it gets fun!

As suggested by a lot of users on the Away3D forums, it may be better to have a 3D artist create objects in Blender or 3ds Max (I do not know if Unity3D can be used, although I hope it can). Once those objects are created, there is a way to import/load them into Away3D.

But in this case, since I do not know 3D software and because there is no need yet to get into complicated texture mapping, we are looking at something super simple: put an image on a cube. Most of what follows is a comprehensive summary of a thread that followed my question on Away3D's forum.

First things first: let's create an image. There are specifications to follow when creating an image for a BitmapMaterial.

A texture does not need to be square, however the dimensions have to be a power of two. What this means, is a texture can be 512 x 512 pixels, or 256 x 1024 pixels, etc. I worked with 2048 x 1024 pixels in this case.

Keep in mind that if you image is not square, it will not mipmap. Not fully convinced I understand what it means, as I do now know 3D vocabulary that much, but suffice to say you simply need to set BitmapMaterial.mipmap to false to make it work.

In the case of a cube, you need to cover all six sides. In order to do so, split your image into a 3 x 2 grid, like so:

Do you notice that each part of the image that represents a side of the cube is not square? It does not matter really, since Away3D will map it as a square onto the cube. As long as you respect the grid in your design, it will be good.

Rather than loading the image and in order to make things quicker, I simply embedded it in the code.

ActionScript 3.0:

package
{
import away3d.containers.View3D;
import away3d.materials.BitmapMaterial;
import away3d.primitives.Cube;
 
import flash.display.Bitmap;
import flash.display.Sprite;
import flash.display.StageAlign;
import flash.display.StageScaleMode;
import flash.events.Event;
 
[SWF(frameRate="60", backgroundColor="#ffffff", width="640", height="360")]
public class Main extends Sprite
{
	// + ----------------------------------------
	//		[ CONSTANTS ]
	// + ----------------------------------------
 
	[Embed(source="../assets/images/dice-texture-2048x1024.png")]
	private var ImageClass:Class;
 
	// + ----------------------------------------
	//		[ VARS ]
	// + ----------------------------------------
 
	private	var	_view3D		:View3D;
	private	var	_cube		:Cube;
 
	// + ----------------------------------------
	//		[ CONSTRUCTOR ]
	// + ----------------------------------------
 
	public function Main()
	{
		super();
		initStage();
		addEventListener(Event.ADDED_TO_STAGE, addedToStageHangler);
	}
 
	// + ----------------------------------------
	//		[ PRIVATE METHODS ]
	// + ----------------------------------------
 
	private function initStage():void
	{
		stage.align = StageAlign.TOP_LEFT;
		stage.scaleMode = StageScaleMode.NO_SCALE;
	}
 
	private function init():void
	{
		// create a Bitmap from the embedded image
		var image:Bitmap = new ImageClass() as Bitmap;
 
		// create the BitmapMaterial
		var material:BitmapMaterial = new BitmapMaterial(image.bitmapData);
		material.smooth = true;
		// little trick: you do not need to care if the image is square,
		// simply evaluate if the sides are even
		material.mipmap = (image.width == image.height);
 
		// create the cube
		var cubeSize:uint = 240;
		_cube = new Cube(material, cubeSize, cubeSize, cubeSize);
 
		// add the 3D elements to the stage
		_view3D = new View3D();
		_view3D.scene.addChild(_cube);
		addChild(_view3D);
 
		// add a listener so it becomes possible to render the 3D world
		addEventListener(Event.ENTER_FRAME, enterFrameHandler);
	}
 
	// + ----------------------------------------
	//		[ PRIVATE METHODS ]
	// + ----------------------------------------
 
	private function addedToStageHandler(event:Event):void
	{
		removeEventListener(Event.ADDED_TO_STAGE, addedToStageHandler);
		init();
	}
 
	private function enterFrameHandler(event:Event):void
	{
		// increment the cube's rotation values to see its different sides
		_cube.rotationX++;
		_cube.rotationY++;
		_cube.rotationZ++;
 
		// render the 3D world
		_view3D.render();
	}
}
 
}

Fix the Away3D sources

Now, I ran into an issue when I originally tested this (Flash Player 11+ needed, click and drag to move the cube):

Some sides were repeated or not applied properly. That is actually what prompted me to ask my question on the forum, as I thought I had done everything proper.

I actually did, but here also, there was a correction needed in the Away3D sources. Away3d forum member 80prozent posted a fix.

Look at the function Cube.buildUVs() into the away3d.primitives.Cube class and replace this part:

ActionScript 3.0:

for(i = 0; i <= _segmentsW; i++)
{
	outer_uv = u_tile_step + u_tile_dim * (i / _segmentsW);
 
	for(j = 0; j <= _segmentsD; j++)
	{
		uvData[uidx++] = outer_uv;
		uvData[uidx++] = 1 - v_tile_dim * (j / _segmentsD);
		uvData[uidx++] = outer_uv;
		uvData[uidx++] = v_tile_step + v_tile_dim * (j / _segmentsD);
	}
}
 
for(i = 0; i <= _segmentsH; i++)
{
	outer_uv = v_tile_step + v_tile_dim * (i / _segmentsW);
 
	for(j = 0; j <= _segmentsD; j++)
	{
		uvData[uidx++] = (u_tile_dim * ((_segmentsD - j) / _segmentsD));
		uvData[uidx++] = 1 - outer_uv;
		uvData[uidx++] = 1 - (u_tile_dim * ((_segmentsD - j) / _segmentsD));
		uvData[uidx++] = v_tile_step + v_tile_dim * ((_segmentsW - i) / _segmentsW);
	}
}
 
target.updateUVData(uvData);

with this part:

ActionScript 3.0:

for(i = 0; i <= _segmentsW; i++)
{
	outer_uv = u_tile_step + u_tile_dim * (i / _segmentsW);
 
	for(j = 0; j <= _segmentsD; j++)
	{
		uvData[uidx++] = outer_uv;
		uvData[uidx++] = 1 - v_tile_dim * (j / _segmentsD);
		uvData[uidx++] = 1 - outer_uv;
		uvData[uidx++] = 1 - (v_tile_step + v_tile_dim * (j / _segmentsD));
	}
}
 
for(i = 0; i <= _segmentsH; i++)
{
	outer_uv = v_tile_step + v_tile_dim * (i / _segmentsW);
 
	for(j = 0; j <= _segmentsD; j++)
	{
		uvData[uidx++] = (u_tile_dim * ((_segmentsD - j) / _segmentsD));
		uvData[uidx++] = 1 - outer_uv;
		uvData[uidx++] = 1 - (u_tile_dim * ((_segmentsD - j) / _segmentsD));
		uvData[uidx++] = v_tile_step + v_tile_dim * ((_segmentsW - i) / _segmentsW);
	}
}
 
target.updateUVData(uvData);

His fix corrects the way the image is applied to the cube. I guess this will be eventually fixed, but at the time of writing this post, the sources provided by Away3D still need that correction.

And there you go! From then you can have an awesomely decorated cube with the texture of your choice!

Recently I had been approached to develop an interface for a huge interactive wall. The company has its own engine, but the interface runs as a Flash Player piece within that environment. I am not talking about Scaleform, which allows game developers to integrate interfaces built in AS3 into their projects, but the logic is pretty much the same.

So the idea was to use some simple 3D shapes and let users interact with it via a touch screen. The project did not go through, however I had done some research on the latest Flash Player beta developments and the latest alpha release of Away3D. As expected, I had to do a lot of searches in Google, I cursed at my computer once or twice, but I did learn a lot. I think it would be nice to share my discoveries.

Setting up FDT to publish onto Flash Player 11 Beta

I have to say a lot of people wrote blog posts already on how to do that. Although their posts explained more on how to use the incubator version of Flash Player, it's pretty easy to do a parallel. I'll just list the steps here and provide the sources to my information further down.

1. Get the latest available Flash Player debugger, Flex SDK and playerglobal.swc (by the way, since the IDE is now called Flash Builder, why is the SDK still called "Flex SDK " rather than "Flash SDK"?)
2. Uninstall whatever version of the player you have on your computer and install the latest one you have downloaded
3. Replace the playerglobal.swc in the SDK with the separate playerglobal.swc you have downloaded
4. Set up the SDK in FDT
5. When creating a new project, make sure to add the -swfversion=13 compile argument (I hope this will be dropped when the release is no longer in beta)
6. In your HTML page, do not forget to set wmode="direct" so the rendering can be done on the GPU

Now these steps are really well explained here, although since the release of the beta version (rather than the incubator version), it is no longer necessary to remove the flex.swc.

Now, all this is a bit of work to get running, and just recently, FDT released a template that sets up a lot of that stuff already. This template includes the compiler argument and an HTML template that presets the wmode, it even includes the M2D library, which is supposed to help creating 2D elements with the Stage3D API to enjoy the benefits of GPU rendering. Thanks guys! I guess now I want to look into creating templates.

Setting up Away3D

I have been reading good comments here and there about Away3D, and the running examples I have seen were quite convincing, so I decided to look into it. Getting started is quite simple.

1. Download the Away3D 4.0 alpha release
2. Add the provided source files to your classpath
3. Add the provided Apparat LZMA decoder library as well

Logically, this should be it and you should be able to go, but nooo! Have you ever seen a development project work properly on the first try? Especially not a project that uses both an alpha release and a beta release! After a bit of research, I found an article on DisturbMedia's wiki that basically explained the situation:

Most errors come from AGALMiniAssembler.as. I'm not sure why, but I found that if I split the multiple classes nested in the single file into multiple files that fixes most of the errors. At the end of the process you should have 3 additional classes: Sampler, Register and OpCode.

Once the split classes are added, some errors remain in the Away3D sources, however it is possible to compile an empty project at this point.

Next, you would expect to be able to use some Away3D classes already, so did I. The base requirement is to add a View3D, which contains a container that can be used as some sort of stage. Let's try:

ActionScript 3.0:

package
{
import away3d.containers.View3D;
import flash.display.Sprite;
import flash.display.StageAlign;
import flash.display.StageScaleMode;
 
public class Main extends Sprite
{
	private	var	_view3D	:View3D;
 
public function Main()
{
	// set the stage
	stage.align = StageAlign.TOP_LEFT;
	stage.scaleMode = StageScaleMode.NO_SCALE;
 
	// create the View3D
	_view3D = new View3D();
	addChild(_view3D);
 
	//
	addEventListener(Event.ENTER_FRAME, enterFrameHandler);
}
 
private function enterFrameHandler(event:Event):void
{
	// render the View3D at every frame (or other update of your choice)
	_view3D.render();
}
 
}
 
}

Try and run that with the explanations I have given so far, you'll most probably run into the same situation I did: an error. Why? I mean, nothing seems wrong.

Here again, it took me a bit of research, but it turns out that a class needed a correction to handle a change made by the beta release of Flash Player. As I understand, this library was mostly written while the player was still an incubator release. Simply get that updated Stage3DProxy class with the one provided in the forum thread, and you're good to go.

From this point on, you can head to minute 2:30 of John Lindquist's tutorial to see how to add an awesome cube to your project, or look into the Away3D examples. Enjoy!

Thanks to Antti Kupila, I have been given a copy of Emanuele Feronato's book Flash Game Development by Example to read and critique. Emanuele has been blogging about Flash gaming for years, and since I am looking to get into gaming, I was eager to read the book.

So far I have made it only through the first three chapters. I did a preliminary critique of the book on the Amazon product page:

Emanuele Feronato has been blogging ([...]) good tips on Flash gaming and PHP development for a while now. When I learned he had written a book on how to get into game development, I had to try it.

In line with his blog, Feronato's writing is clear and concise, no fluff is added. A good thing is that he assumes the reader has already some knowledge of Flash and AS3. This book does present some basic information if you know nothing of Flash, but the intent of this book is to teach you how to do games, not how to program. This is really a good thing, for there are way too many books that think that all readers have never touched programming of their life.

Feronato does a good job at increasing the difficulty of concepts during each chapter. His introduction to each challenge, by splitting the concept and the coding, guides the reader properly.

As a web developer, jumping into gaming is a good and honest challenge. Oftentimes a web dev tends to create complex systems for data and views. Feronato brings back the joy of programming with simple and logic code structures.

I did get put off by the fact that his instructions make use of the Flash IDE, rather than Flash Builder, FDT or FlashDevelop. In a professional environment, it's quite inefficient to code in the Flash IDE, but I believe it would have taken too many explanations to put in a book about games. All in all, it is quite easy to transpose the instructions into code-only IDEs.

I would also have like some more game-oriented optimization tips (like using multiplications rather than divisions, since it is quicker), for gaming is all about being code-efficient. That said, it is a good buy for those who are serious about getting into Flash gaming.

I have read the other critiques of the book on Amazon and also other critiques from real game devs like Iain Lobb and Rasmus Wriedt Larsen and it got me thinking.

Critiquing the critique

My grandad used to say: "Only a fool does not change his mind." Whereas I do not think as harshly about the book, I do want to delve deeper into my critique to either correct what I said, or even add to it.

Lobb mentions the coding style of Feronato, which I also noted looks a lot like PHP's style:

We all write weird looking code sometimes, but I think a book needs to set a better example.

I must say that it did not deter me really too much, since I am used to pick up other people's work and fix it. However, now that I think of it, a book must set an example of good coding practices. I have to agree with Lobb on his critique.

Another practice that really should have been present in Feronato's code is tips that make code execute faster.

Using var array:Array = [] may look dirty, but it is way quicker than creating arrays with the new Array() declaration. His examples do not use many arrays, but I do not see why good habits should not be put forward.

Another tip is to try and use multiplications rather than divisions. Again, the examples do not use calculations that are processor intensive, but it is the best moment to explain to new game developers tips that will help them when they have to handle complex systems in the future.

But those tips are something that I knew already and that could have been used in the first three chapters of the book. Let's see when I get further in the book how it goes.

Both Lobb and Larsen look onto Feronato's code as merely scripts, for it doesn't push OOP concepts. As Feronato's book is really built on iterating his code and moving it forward, as many oftentimes code in real life, it would have been nice for him to explain how to transform hid code into classes etc. The speed at which Feronato moves through concepts means the reader is expected to know how to code. And if so, the reader could also then be expected to know some OOP. Feronato could have used such a premise to then push the use of classes. Unknowingly, I worked exactly how Larsen describes what he sees in his book:

[...] if you know how to code AS3 with OOP and good coding practises, plus being able to extract general ways of doing something from very specific examples [...]

As I mentioned in my Amazon critique, I would have preferred it if the author would have not used the Flash IDE to code, since it's pretty backwards. As I was going through his examples, I actually used FDT to create a proper project structure, with assets, packages and different classes for specific tasks.

I did enjoy Feronato's scripting style to read, but I do now think the book he wrote should have promoted practices that would be useful in professional environments.

Lobb critiques Feronato's choices of games for being out of touch with current trends. He makes an interesting point:

I really think that a lot of game developers around my age group (e.g. 25 and older) are stuck in the past somewhat with their ideas of what constitutes a computer game.

I think that using a lot of pixel sprites in my prototypes casts me in that group. However I must disagree with Lobb here. I am not fan of Flip and Match games, Tetris or other classic puzzlers per se. As good a developer I am, I have never tackled a real game project. Starting from scratch with basic concepts and logics actually helps me learn things properly.

For example, in Minesweeper, the logic of how to use and create a flood fill function is explained. Since I come from a web development, where the UI is usually the most important concern, I would not know what to call such a concept. It is a definite win for me here.

Another example is the Connect Four winning explanations. Feronato explains how a win is made in concepts and how to translate that in code. I know pseudo code is not something new in development, but learning to do it for gaming is, to me and maybe to other non-gaming developers, something refreshing and useful.

Let's take a look at what I was able to create with what I have read so far.

Concentration, a flip and match game

This game is pretty straightforward, we pretty much all know it. Feronato explains in simple terms how to build such a game.

What is missing however is an explanation for the reader on how to reset the game so the player can enjoy more than one game. Actually, the author does not explain how to restart any of the games he describes. That is a big part in gaming, it should be present in his book I believe. It would also have been a great way to show how to use functions. So as you can see from my prototype above, I have added that logic. Once the game is complete, the user can retry to play.

Stats on how the game progresses is also interesting for the player to see. Lobb actually mentions this in his critique, although I had though of adding these stats previous to reading the article.

As a personal touch, I decided to make my game shareable on Facebook's wall so that my friends could try that little prototype in their news stream. I will eventually explain how easy that is, but it is not the point of this blog post. You may try it yourself in sharing the URL http://jansensan.net/experiments/game-dev-concentration/ onto your news stream. Do not just copy the URL into your browser, it redirects to this post.

Once you share the above URL onto your news stream, it will then show like this:

If you ever used YouTube or Vimeo on your news stream, you know the Flash piece will expand when they click on the blue play button.

With those simple additions, people were enjoying a simple prototype and sharing it around.

Minesweeper

To be honest, I never understood the Minesweeper game, or rather what is compelling to play it. Or maybe I just hate it because that is the only game that was available on my dad's work computer at the government when I was visiting and he was asking me to wait for him... Anyways, I digress...

Feronato only explains what makes the player lose the game, however he should also have explained what is the win situation. An author cannot take for granted that the reader knows the game that is described.

With this game, Feronato explains some recursion and the concept of the flood fill, which I believe is well worth to learn.

Concerning the use of functions however, the explanations lack. Functions are made to reuse code and, again, restarting a game is the perfect need to reuse code. As you can see from the prototype, you can only play once, which as I mentioned before is not a way to build a complete game.

Maybe I have not read enough tech books, but whenever I stumble upon an example online that uses events, the tutorial not always explains that it is best to remove the event handlers, sometimes even in Adobe's documentation! Many a time did I have to explain or correct other people's code to reduce the demand on memory. Feronato does explain to remove the event handler, I have to give him props for this.

Connect Four

This game is not digital by any means, and recreating it does not make it more fun. However, the logic learning with this game is quite nice. Games like Drop 7 seems to be a game that extrapolates on the concepts defined in Connect Four.

The structure of the code in this game made me cringe. I believe that under no circumstance should a child tell its parent what to do. Sounds logical no? I mean not only about code, just read the previous sentence aloud and you will feel how much sense it makes.

Feronato actually does that here, he write something like this.parent.parent. It is not technically wrong, since it compiles, but I believe that conceptually it is not right. It makes it so complex for someone else to inherit a project and try to figure out such a logic. Big no-no.

While explaining how to check for the game completion, the author does bring forward the idea that is it not efficient to loop through all possible tiles. Good suggestion on code efficiency here.

So, what now?

I do see that this book has some flaws, but nothing that could not have been corrected or pushed more. I think also however that both Larsen and Lobb have dismissed a couple of things in their critique.

a) The audience. Larsen makes a good point that the code is quick and dirty and that the prototypes are not teaching concepts, but that is exactly what the introduction says:

Who this book is for

• AS3 developers who want to know quick and dirty techniques to create Flash games
• Flash animators who want to learn how to create games from their works with AS3
• Programmers who know languages different than AS3 and want to learn AS3 to make something more interesting and fun than the old "phone book"
• Even if you aren't a programmer, but you love Flash games, you can count on this book: you will be guided step by step with clear examples and the support of the full source code of every game

Now, is that audience right? That's another question, but it is clearly stated.

b) The types of game. Lobb did hit on that and I do what to bring it back. The title of the book clearly states that is for building classic games, mostly puzzlers.

Build 9 classic Flash games and learn game development along the way

Again, the question to raise is, is that a good thing to teach devs? With Stage3d (a.k.a. Molehill), P2P, game controllers on AIR and all sorts of awesome features, Flash can be so much more as a gaming platform.

All in all, I will go on reading the book, for I know I will learn some more things. I agree however that this book does not feel complete, but it feels like a good primer to get into game development. Hey, I may also be wrong, but once a reader knows about some concepts like AI, recursion, etc., it then becomes more possible to search for more precise concepts.

Whether it's a game, a website, a video or even a subsection in these projects, it seems that they all need a share button. I personally believe it is sometimes too much, to the point that it seems that the PR and media teams avoid doing their work in the hopes that the customer/user will spread the word for them. But that may be just me complaining again.

Nevertheless, I will present here how to use the simple sharing functionality of some of the most prominent social networks around. Remember that Facebook and Twitter are not king and queen everywhere, you may want to target your markets properly.

 Facebook

The infamous social network. As a developer, I kind of like to hate this network, for its documentation is poor and quickly outdated. On the other hand, if Facebook changes its API this often, it allows them to implement new stuff quicker.

Facebook has a relatively simple sharing functionality, even some additional info that you can put on your site metadata to display on the user's wall. I am not taking here about the Like button, which would display number of "likes"—although these two functionalities were merged.

In order to share, you do not need Facebook connect at all, you would only need it if your application, game or site requires access to the user's data. You simply need to call a URL:

http://www.facebook.com/sharer.php?u=http://example.com&t=The Post's Title

If we deconstruct the URL, it's pretty easy to see what is what:

Keep in mind however that if the site that you share has a title and description metadata, the value that you set to t will be overwritten.

You may also want to push it further and set yourself the title, the description and even a thumbnail for your site. For example, this is what was done for the adidas Porsche Design site:

In order to set those values, simply add the Facebook metadata tags on the page you wish to share, like so:

HTML:

<meta property="og:title" content="Your website title goes here"/>
<meta property="og:description" content="Your website description goes here"/>
<meta property="og:image" content="http://www.dummyimage.com/50x50"/>

You may read more in the Facebook documentation. (I can't believe I just wrote that...)

 Twitter

The way to share on Twitter is pretty similar to Facebook's, if not simpler. Here as well, you may simply use a URL with some parameters:

http://twitter.com/share?url=http://example.com&text=This tweet has been shared via a URL.

Here again, here is a breakdown of the URL:

 LinkedIn

LinkedIn also offers a simple URL for sharing:

http://www.linkedin.com/shareArticle?mini=true&url=http://example.com&title=The Post's Title

Their share URL contains an additional parameter:

LinkedIn provides well explained documentation on how to use their sharing functionality. Although for the life of me I don't get why I would ever use the summary parameter.

 ВКонтакте (vKontakte)

ВКонтакте's share is well documented. Can't read Russian? Get Google Chrome, it translates websites quite well.

Even though there is a lot of options available for sharing, let's look at a simple share:

http://vkontakte.ru/share.php?url=http://example.com&title=The Post's Title

Pretty much the same as Facebook:

 人人网 (RenRen)

We now enter the realm of assumptions, I simply relay information I found about how to share on RenRen. A user named Yuao shared his knowledge, and it seems that again, a simple URL with some parameters do the trick:

http://share.renren.com/share/buttonshare.do?link=http://example.com&title=The Post's Title

Let's see what that URL is made of:

Due to the documentation being all in Chinese, it's kind of hard to obtain more information. As far as I know, Google cannot sift through stuff in China easily. Also, the company itself did not want to provide help unless huge sums were paid upfront.

Other networks

There are obviously other networks, but as you can see from the last one of which I spoke, my knowledge gets thin. Hyves, Orkut and Mixi may be of interest if your data shows that your users are part of such networks.

As for every project, make sure that implementing the sharing functionality makes sense. It may be obvious, but not all networks need to be targetted for every single project.

If you target multiple markets and social networks, do look into the proper etiquette of each. Last I heard, commercial presence was a bit frowned upon on Mixi.

That is useful while debugging, however most often those traces are needed in the final context of the Flash piece, like a website.

There are some awesome tools out there that do just that and in style. I'm thinking of De MonsterDebugger. That tool is really good, although it requires some additional classes and long words to write to get something simple (eg: MonsterDebugger.trace(this, "Hello World!")).

There is a context in which that tool cannot be used, and that is Facebook. Ah! the ever hatable social network platform! Facebook does not allow ExternalInterface for security reasons, that is why tools like De MonsterDebugger are not available, this is how data is sent to their debugger. Edit: After receiving a comment, I investigated, it indeed turns out that MonsterDebugger is available when working on Facebook, as it indeed uses LocalConnection. My bad for assuming. However, the use of ExternalInterface is still not possible on Facebook, and the point of this post is more to show how to use the Terminal and Command Prompt to debug.

Sure you could create a textfield and add it to the display list, but that can become tedious if you need to add scrollbars and such.

A good alternative is to use a debugger that functions regardless of context. Adobe's open source Flex SDK comes with the Flash Debugger, a JAR package that can be run with Java from the command line.

Yikes!

That sounds more complicated than it really is actually. Let's see how to run the debugger on Mac OSX and Windows.

Terminal on Mac OSX

The screenshot above provides already a lot of information on how to run that package, but let's spell it out step by step:

1. Open Terminal
2. Go to the directory where of the Flex SDK you want to use
3. Go to the "lib" directory
4. In that directory, you need to run the "fdb.jar" package. To do so, type "java -jar fdb.jar"
5. To start the debugger, type "r", for run. The traces and errors will then be displayed in the Terminal

This will work for all SWFs published with debugging enabled, whether they are local or online, and that is where it becomes useful, for debugging stuff online. Just make sure then that you installed the debugger version of the Flash Player so it can communicate with the Terminal.

Command Prompt on Windows

It's pretty much the same on Windows with the Command Prompt. You can see here that I use Windows XP, so I'm sorry if there are slight differences on Vista or 7, I don't have those OSes.

1. Open the Command Prompt
2. Go to the directory where of the Flex SDK you want to use
3. Go to the "lib" directory
4. In that directory, you need to run the "fdb.jar" package. To do so, type "java -jar fdb.jar"
5. To start the debugger, type "r", for run. The traces and errors will then be displayed in the Command Prompt

Happy debugging!

Aah, the joy of being able to obtain code completion during development, what dev doesn't like this? A while back, I explained how to link to SWCs to get code completion, but not compile said SWC in the SWF, so it could be loaded at runtime. It turns out that all IDEs do not necessarily behave the same way Flash Builder 4 does. Figures...

Ever since I went to Flash on the Beach, I have been playing with more IDEs than Flash Builder. I have to say I've been quite lucky: all attendees were given the FDT 4 Pure IDE. Also, I have been one of the lucky winners of an IntelliJ IDEA 9 licence. And since I was already trying all sorts of IDEs, why not look at FlashDevelop, an open source IDE, sadly available only on Windows.

When I look at the metrics of my blog, it seems that loading a SWC at runtime (along with the post about Facebook and AS3) is the most popular subject, so I though it would be better if I was more thorough and explain how to repeat the workflow mentioned above for all these IDEs. Obviously, if anybody knows even better ways to go about what I'm about to explain, by all means share with me.

Flash Builder 4

I already published a post about this workflow and this IDE, simply refer back to it.

FDT 4

FDT is pretty much the same thing as FlashBuilder, albeit better. It is also based on Eclipse, but all those plugins I needed or those that some devs boasted about, they are already in place in FDT.

When you want to add an SWC, I must say it's quite simpler here. No need to go hunt in the preferences's subcategories. Right-click on that SWC, the select "Source Folder > Add to Classpath".

Now, the small issue that this presents, there is no prompt that asks whether you want to embed said SWC in your code, or to load it at runtime. I hunted a bit for this one, but in the end it takes s simple manual change. I was wrong on this one, as pointed out by Mattes Groeger:

[...] you can set this option via GUI. Just call the project “Properties” window by right clicking the project in the Flash Explorer view. Then in “FDT Build Path” click on the “Build Order” Tab. Here you can choose for each library via check box if it should be used as runtime library or not.

Alternatively, you can still go and play with the settings file, as I explain below.

Whenever you create a project in any Eclipse-based IDE, a .project file is created. With FlashBuilder, there is also a .actionScriptProperties. Do not worry if you have never seen these files, they are "invisible." They are actually XML files that contain project configurations. I'll probably have to come back to these sometime in the future.

I was then thinking, FDT probably creates those files too. Lo and behold, it does! Now, how do you edit these? At the top right of the Flash Explorer panel, there is a triangle pointing down. In there, select " Filters...".

From there you can select what types of file you want and do no want to see. Personally, I really dislike it when there are hidden files, so I want to see all of them. Once you have that in place, you will be able to find the .settings folder.

I mentioned the .actionScriptProperties for FlashBuilder, for FDT you want to open com.powerflasher.fdt.classpath. In there, all the sources paths are listed. In order to change an SWC so that its code is not embedded in the SWF, change the useAsSharedCode attribute from false to true. Then just make sure you load your SWF before you instantiate any class from that shared library.

Voilà for FDT.

IntelliJ Idea

Now for another beast altogether. I must say I have not been able to familiarize myself much with this IDE yet, and I find it a bit more complex than necessary. I mostly had to refer myself to Jesse Freeman's posts about the AS3 in IntelliJ IDEA workflow to be able to set up and compile a basic project. Once that behemoth in the room is taken care of and you know where to add SWCs and sources as libraries, it turns out to be simple.

First, right-click on your project (which is called a module in IntelliJ IDEA) and select "Module Settings".

In these settings, select your module and go to the Dependencies tab. If your SWCs are not there already, add them with–you guessed it!– the "Add" button. At the right of the path to that SWC, there is a combo box from which you can select options for the scope: "Compile", "Test", "Runtime" and "Provided". The one we need to choose in this case is "Provided".

You can now go about your business for the rest of your project.

FlashDevelop

Working with FlashDevelop is a bit tricky for me, since I'm on a Mac. However, back when I was working at an e-com shop 3 years ago, I was using FlashDevelop, I should be alright. What really help I have to say is that this tool has an active community, which saved me a great deal of trouble. A search on Google and I got this forum thread which answers all my questions. So, credit given when credit due, now let's look at what is to be done with FlashDevelop.

First, select your SWC from your library, and from the contextual menu, choose "Add To Library".

Once the SWC is added, the label will show in blue. Right-click again on it, and then the "Options" menu is visible.

In that window, you are presented with the necessary options. In this IDE as well the terminology changes, but at least a description is given. Check "External library (not included)".

Ant

As you will see from the sources I provide at the end of the article, all these IDEs actually play along quite well. But if for one reason or another, you are more the I-don't-depend-on-no-IDE kind of person, you can also compile your project directly into Ant. I know that after I have written my post about Ant, I should have written about how to compile with said insect, but since I faced the loading a SWC at runtime issue first when I started dabbling with FDT, I thought about writing about this workflow first.

Let's get to business. In ant, you need to use the runtime-shared-library-path tag so that when you compile your code is checked against your library, but that the library is not included.

<runtime-shared-library-path path-element="${ASSETS_DIR}/swf/assets.swc">
<url rsl-url="${ASSETS_DIR}/swf/assets.swf"/>
</runtime-shared-library-path>

Specify in the path-element attribute the path to the SWC, and in the rsl-url attribute of the url tag against what SWF the SWC is compared.

Simple no?

Conclusion

This is actually the first time I try to do something and see how each IDE behaves. I'm quite happy to have found out that all of these play well together, that is good news to know that if you commit all of your project built in one IDE to SVN, that another developer can check it out and run it in another IDE without conflict.

However, one thing that did bother me is the amount of crap (the worst are Flash Builder and IntelliJ IDEA) that these idea create, there are so many useless files! And I am sorry for this, they are all part of the sources as well.

More related to the issue though, it is nice that all IDEs offer a way to work with code completion of assets at development time.

Sources

As promised.

As developers, there are inevitably repetitive tasks that need to be done and redone with each new project we undertake. The best example I can provide is creating the folder structure for our projects. Obviously this is personal to each dev, and there is also some stuff that some of our IDEs–hmm, I'm looking at you Flash Builder–add by themselves. Oftentimes I have simply copied/pasted the structure from project to project, even created a folder structure without any files, just so I could copy paste. That was a while ago.

In line with the mission of this blog, I present you with another useful tool: Ant.

Ant is basically a set of tasks written in an XML file. Tasks such as moving and copying files and directories, but sometimes much more powerful stuff. If I am not mistaken, this is how a lot of patient developers call manually on the compiler from the Flex SDK to create their SWCs and SWFs.

As I said in my previous posts, I never pretend to be a master at what I explain, but I like to share functional and straightforward knowledge of the tools, languages and utilities I use.

Of IDEs and Ant

As I have mentioned a couple of times, I do not use the Flash Builder 4 standalone IDE, but rather FB4 as a plugin to my Eclipse IDE. I once mentioned that already-integrated XML editor of Eclipse was an advantage over the standalone FB4. Here also Eclipse wins. Go to Window > Show View... > Other... and this is how you obtain a convenient Ant view panel.

FDT also offers such a panel, so does IntelliJ IDEA, however I have no idea what is available for FlashDevelop. For the standalone version of Flash Builder, a search on Google quickly provides examples of how to add the panel to the IDE.

Now, let's look at some Ant stuff!

Structure and conventions

Usually, Ant files are called "build.xml" and are placed in the "build" directory. That directory also contains a properties files called "build.properties."

Let's look at them.

a) build.xml

Ant being an XML, it is obviously written in tags. However contrary to XML, tag names are important here:

Ant:

 
<project name="Project Name" default="Default Task Name" basedir="../">
	<!-- your tasks here -->
</project>

So as you can see, the root tag is named  "project" and it contains some attributes:

• The "name" attribute is the label that will be presented in the the Ant view panel.
• The "default" attribute is the task that is called by default. More explanations on that further.
• The "basedir" attribute is the base directory from where the tasks are called for moving, creating, etc.

b) build.properties

The properties file is a variables container.

Properties:

projectname=Tutorial_AntToLeverageInteractiveDev
 
source.filename=Main.swf
source.debugdir=bin-debug/
source.releasedir=bin-release/
 
target.filename=deployed-file.swf
target.deploydir=www/

Simply write the variable name, an equal sign ("=") and the value. There is no need for semi-colon at the end of the line.

To import it in the build, use the property tag. As we have seen, all paths are relative to the value of the basedir tag, defined before.

Ant:

 
<project name="Project Name" default="Default Task Name" basedir="../">
<property file="build.properties" />
</project>

Now all those variables are available for you to use in your tasks. The syntax to use a property is simple: start with a dollar sign ($), and put the property name in curly brackets ({}).

Ant:

<echo>This property has a value of ${someProperty}</project>

Tasks

Tasks are basically Ant functions or methods. The Apache Ant Manual is full of examples that can be used quickly, but if you have never used Ant, it might be overwhelming. Let's start by looking at simple things that can be done.

One main thing that annoys me with Flash Builder is the superfluous use of the html-template folder and wrapper. Also, if I happen to put any directories or file in the bin-debug, they got overwritten for all sorts of reasons. I then took the habit of having some folders of my own at the root level of my project, namely:

• assets (for the assets used by the application)
• build (for the Ant tasks)
• libs (for external libraries)
• res (for all resources that the application does not use, tracking plans, copy decks, etc., which is not committed to SVN)
• www (the folder which actually contains the deployment files)

As I create these directories for most of my projects, it was becoming tedious to create them all the time. This is where Ant is your friend.

Ant:

<target name="Create AS3 Project Directories">
 
	<!-- create the assets directories -->
	<mkdir dir="assets/css"/>
	<mkdir dir="assets/fla"/>
	<mkdir dir="assets/fonts/osx"/>
	<mkdir dir="assets/fonts/win"/>
	<mkdir dir="assets/images"/>
	<mkdir dir="assets/sounds"/>
	<mkdir dir="assets/swf"/>
	<mkdir dir="assets/videos"/>
	<mkdir dir="assets/xml"/>
 
	<!-- create the libs directories -->
	<mkdir dir="libs/src"/>
	<mkdir dir="libs/swc"/>
 
	<!-- create the www directories -->
	<mkdir dir="www/assets/css"/>
	<mkdir dir="www/assets/images"/>
	<mkdir dir="www/assets/sounds"/>
	<mkdir dir="www/assets/swf"/>
	<mkdir dir="www/assets/videos"/>
	<mkdir dir="www/assets/xml"/>
	<mkdir dir="www/css"/>
	<mkdir dir="www/js"/>
	<mkdir dir="www/images"/>
 
</target>

The only thing needed when I start a new project is to copy my Ant build to the new project and then launch the Ant task, and all folders are created quickly. Let's analyze what I presented above.

The target tag contains the tasks. It is mandatory to give it a name, hence the name attribute. Inside that tag is where you place the Ant tasks, such as mkdir (make directory).

It is interesting to note that you can immediately create a directory inside another one, even if the root one does not exist. Calling mkdir with the attribute "www/assets" will create both the "www" and the "assets" directories at once.

Refreshing the workspace

Whenever files are modified outside of an Eclipse-based IDE, it is good to refresh the workspace. When creating, moving, deleting or renaming files in Ant, such a refresh is also necessary. It is however quite annoying to do this manually every time.

The first time you run an Ant task, it will then be added in Eclipse's External Tools Configuration menu. You can access it by clicking on the button that has sort of a suitcase icon.

Earlier I wrote about the default task of the build task. I usually echo the timestamp as the default task, so I can then simply double click on my build in the Ant view to trigger it and avoid creating or deleting stuff too early. Then I go to the config.

Let's take a look at them.

The first thing you want to do in these configs is to make sure that you check the "Run in the same JRE as the workspace" in the "JRE" tab, so that the refresh succeeds. Obviously, if you have other used for the JRE, rely on your knowledge, but for generic AS3 development, this serves my purpose.

Then, head to the "Refresh" tab and check what you want to refresh once the Ant build has completed.

Look at the ants on the floor
They work real hard, lifting three times their mass
And sometimes more

Nick Diamonds could not have phrased it better when he sung Let's Get Known. What I presented here and what I know of Ant is but a small part of what it can do. When you realize that you repeat actions often in your Finder or Windows Explorer, think of this tool, it will save you time.

For a recent project, we needed to have AS3 communicate with Facebook and the other way around. Facebook have created a whole framework around their application, which I believe makes some sense for security purposes, but is unfortunately not documented in an orderly manner.

I do not pretend that I am the first one to write a post about how to communicate between AS3 and Facebook Javascript (or FBJS), but all those tutorials I found expected you to know some thing or another about programming for Facebook, never taking it from the start. So, here goes, communication between AS3 and Facebook for dummies. Or beginners, if you feel offended by the dummy title. Or if it infringes on patents and stuff.

Of knowledge and tools

In this tutorial, I do assume that you have some knowledge of the tools I will present, namely AS3, HTML, JS, CSS and PHP. You, however, do not need to be a master of all (I sure am not).

As presented before, I work in Eclipse, meaning that with the Flash Builder 4 plugin, the Web Tools Platform and the PHPElipse plugin, I only need one environment. You will also need to make sure that your server runs PHP. Locally, you can use MAMP to run a PHP server (thanks to Antti Kupila for the tip on that one).

Facebook's framework

Before we go on writing any code, maybe it is good to know a bit how Facebook works. In order to run JS, Facebook have their own subset or framework which they dubbed FBJS.

To embed an SWF, you need to create an fb:swf tag. Also, the Flash component does not start automatically, there needs to be a user interaction to trigger the embed of the SWF. It might be be of interest to mention that Facebook supports certain versions of Flash, namely 9 and 10. The exact version numbers can be found in the notes of the fb:swf tag.

The index file

Using PHP is totally optional in this case. Facebook does have a habit of caching files on their servers, therefore instead of having to hardcode all URLs, it is quite practical to use PHP variables. For images and CSS, I sometimes add the time() PHP function so I make sure that the file used is always the latest, like so:

PHP:

$img_src = "http://www.example.com/images/image.jpg?" . time();

The time() function is useful during development, but it is best not to use it once you deploy live.

We also need an id for the image element.

PHP:

$img_id = "click_to_activate_id";

Now, let's look at the JavaScript:

JavaScript:

function embedSWF()
{
	// remove image
	var image = document.getElementById("click_to_activate_id");
	document.getElementById("swfWrapper").removeChild(image);
 
	// create swf object
	var swf = document.createElement("fb:swf");
	swf.setSWFSrc("communication_with_fb.swf");
	swf.setId("communication_with_fb_id");
	swf.setWidth("520");
	swf.setHeight("600");
	document.getElementById("swfWrapper").appendChild(swf);
}}

In this block, I create a JS function that removes an image and generates an fb:swf tag in its stead.

PHP:

This block represents the image that the user will see first. Once the user clicks on the image, the JS function mentioned above is called and the SWF gets embedded.

It is important that the fb:fbjs-bridge tag is place before the wrapper that contains/will contain the SWF, otherwise it will not work.

CSS:

#wrapper
{
	width:520px;
	background-color:#ffffff;
}
 
#swfWrapper
{
	width:520px;
	height:600px;
	margin-bottom:16px;
}
 
#buttonsWrapper
{
	width:520px;
	margin:0 auto;
}
 
.button
{
	cursor:pointer;
	background-image:url(../images/button.jpg);
	width:96px;
	height:16px;
	margin:0 auto;
	padding:4px 0;
	font-family:Helvetica, Arial, sans-serif;
	font-size:16px;
	text-align:center;
	color:#000;
}
 
.hasPointer
{
	cursor:pointer;
}

This last block is just some CSS to hold the visuals together.

Of ActionScript and FBML interaction

Usually, when it is necessary to have AS3 interact with JS, one can simply use the ExternalInterface class. Most probably for security reasons, Facebook makes our lives a bit more complicated when we need such an interaction once in their framework. As I said before, we have to use their FBJS Bridge. Let's see how.

As the SWF is embedded into Facebook, it receives a multitude of variables, which are listed in the older version of FB's doc. There are two that are of interest to us here: "fb_local_connection" and "fb_fbjs_connection". These are the variable names needed to respectively create an outgoing connection and an incoming connection.

ActionScript 3.0:

var _outgoingConnection:LocalConnection = new LocalConnection();
var _outgoingConnectionName:String = loaderInfo.parameters.fb_local_connection;
var _incomingConnection:LocalConnection = new LocalConnection();
var _incomingConnectionName:String = loaderInfo.parameters.fb_fbjs_connection;

In the case of the outgoing connection, we use the name when calling a JS function, like so:

ActionScript 3.0:

_outgoingConnection.send(_outgoingConnectionName, "callFBJS", "fbjsFunctionForAS3", ["Message from AS3", "Hello Facebook!"]);

Note that in this function, the second arguments must always be "callFBJS", as Facebook uses a LocalConnection in an SWF of their own to communicate with JS in their framework.

The third argument is the name of the JS function you need to be called from Flash, and the last is an array of the arguments needed.

JavaScript:

function fbjsFunctionForAS3(title, message)
{
	new Dialog().showMessage(title, message);
}

Another idiosyncrasy of Facebook is that the usual alert() JS function is not available. It may be frustrating at first, but their framework provide a solution that uses their own UI, which can be more interesting. As seen above, you can simply create a new Dialog() and right away call the showMessage() function, a blue Facebook window will pop over your text content. HTML is unfortunately not permitted there.

Now, you may also want to call AS3 functions from JS. Let's take a look at how this would work.

ActionScript 3.0:

_incomingConnection.client = this;
_incomingConnection.connect(_incomingConnectionName);

The first thing to do is to set a client to the connection, meaning what is the scope of the functions that the FBJS Bridge will call. I like to keep it at the same level as the class. Then, connect the connection.

You simply need to make a function available to be called.

ActionScript 3.0:

public function as3FunctionForFBJS(title:String, message:String):void
{
	trace(title, message);
}

And let's see how to call it from the Javascript side:

JavaScript:

function fbjsFunctionForAS3(title, message)
{
	var swf document.getElementById("click_to_activate_id");
	swf.callSWF("as3FunctionForFBJS", "Message from Facebook", "Hello AS3!");
}

Obviously at this point you need UI elements to trigger these functions, but I leave that for you to figure out and create.

Setting up the Facebook application

First, you should head to Adobe's website where some tutorials present you with the basics of what you need to know (link 1, link 2, link 3).

Once you created your app and all, make sure that your "Render Method" is set to "FBML" in the app settings:

There you go! You are now ready to have your Facebook projects communicate with AS3 and vice versa.

Resources

You may get the sources for this tutorial here.

You may test what I have presented in this tutorial: http://apps.facebook.com/flash-to-fb/.

A while back, I thought of adding a touch screen film onto my laptop's screen, so I could use Max/MSP/Jitter's incredible sound processing tools and interface more easily than keyboard and mouse in the context of an installation or a performance. It turns out that a couple of years later, screens are touchable more easily, although I have yet to find a tablet that will be interesting enough for me to buy and want to use with Max.

Nevertheless, I had fiddled around with AS3 to communicate with Max. I had planned for a while to write a post about this, but I thought it was more important to present how to start and manage a project. What I will present here is how to communicate data between the two software, and since Max is a desktop installation, I will create a pure AS3 Air project.

Just to give credit where credit is due, steps to create the Air project are mostly taken from here. Let's have at it now!

Create an Air Project

Let's first create a Flex project in Flash Builder 4. Right-click in the package explorer window, select "New > Flex Project". Make sure that you check the "Desktop (runs in Adobe Air)" option in the "Application type" subsection, you do not want to make a web project.

In the next window, leave the "Output folder" field as is and click "Next". Then, in the "Main application" field, change the .MXML extension to .AS and click "Finish."

As a habit, I always have a initStage() function. In Air, you need to spawn an actual window, something we never do for the web. This is the perfect place to do so.

ActionScript 3.0:

private function initStage():void
{
	// first, spawn a window
	stage.nativeWindow.activate();
	// then set stage params
	stage.align = StageAlign.TOP_LEFT;
	stage.scaleMode = StageScaleMode.NO_SCALE;
}

In order to communicate with Max, we need to create an XMLSocket.

ActionScript 3.0:

private var _socket:XMLSocket;
private var _host:String = "127.0.0.1";
private var _port:uint = 8080;
private function initSocket():void
{
	_socket = new XMLSocket();
	_socket.addEventListener(IOErrorEvent.IO_ERROR, xmlSocketEventsHandler);
	_socket.addEventListener(Event.CONNECT, xmlSocketEventsHandler);
	_socket.addEventListener(Event.CLOSE, xmlSocketEventsHandler);
	_socket.addEventListener(DataEvent.DATA, xmlSocketDataHandler);
	_socket.connect(_host, _port);
}
 
private function xmlSocketEventsHandler(event:Event):void
{
	trace("\n", this, "--- xmlSocketEventsHandler ---");
	switch(event.type)
	{
		case "ioError":
			trace("\tcould not connect");
			break;
 
		case "connect":
			trace("\tsocket connected");
			break;
 
		case "close":
			trace("\tsocket closed");
			break;
 
		default:
			trace("\t" + event.type);
			break;
	}
}

There are a couple of things to go through here. At the top of this code block, I instantiate the XMLSocket. I also create variables for the host and the port, which are both necessary to connect the XMLSocket.

Then, the initSocket() function takes care of initializing the XMLSocket, also adding some listeners to it and finally connecting it. For the connection, you may want to read about your platform (whether it's Windows, Mac OS or other) to see what is the host IP and what ports can be used locally. You may also read up a bit on the Flash Player security, in case you need a cross domain XML file, although since this project is desktop-based and not going through a browser, I did not need it.

The xmlSocketEventsHandler() simply traces what events the XMLSocket receives.

Create a Max patch

Max files are called patches. It goes back to patching cords, but I won't go too deep into the Max language, you may read all about it yourself on the Internet.

By default, Max does not communicate with Flash, but just like AS3, there are some "libraries" that can be added to Max, they are called externals. A couple of years back, the Flashserver external was easy to obtain from the author's website or from the Max Objects Database, but it is sadly not the case anymore. I still have it and it is bundled with the source files for this tutorial, I hope I am not infringing anyone's copyrights by making it available again.

Then let's create a new patch and add the Flashserver object. This post is unfortunately not about how to use Max, thus I will not explain how to use the software here. I may in some future post, but this is way out of scope for this post.

Simply look at the help for the Flashserver object if you need to, but quickly, after the name is the argument for what port to connect to ("8080") , and the last argument ("256") is the amount of clients or Flash applications that can connect to this Max patch.

Talking with Max

When Flash needs to communicate with other languages and software, the other software usually has the role of a server, therefore it needs to be opened before the Flash/Air app. Thus, make sure you open the Max patch before attempting to communicate with Flash.

First, let's look at receiving what Max may send to Flash. Earlier, there was one event handler that I did not define, here it is:

ActionScript 3.0:

private function xmlSocketDataHandler(event:DataEvent):void
{
	trace(event.data);
}

So the data is actually what Max sends to Flash. To send multiple values to Flash, you'll need to create a pack in Max and send it as a string and then parse it in Flash.

Let's look at the code to send data to Max:

ActionScript 3.0:

_socket.send("hello max;");

It's as simple as that! Note that the data always has to end with a semicolon (";"). In the case where there are multiple values that need to be sent, separate them all with a semicolon, like so:

ActionScript 3.0:

_socket.send("hello max; from flash;");

On Max's side, simply use the unpack object to be able to parse the values into your patch.

Source files

As promised, here are the files that I used to create this project. The Air project was created in Eclipse with the Flash Builder 4 plugin, and the Max patch with Max 5, with the Flashserver external installed.