Understanding Flash’s Coordinate Systems

Have you ever written code like this:

newBullet.x = hero.gun.x;
newBullet.y = hero.gun.y;

…and found that the bullet appears in a seemingly random place compared to the hero’s gun?

Or have you ever traced tank.turret.rotation and found that it always returns zero, even when it’s clearly pointing diagonally?

Maybe you’ve compared the width of two identical objects, one obviously double the size of the other, and found that Flash thinks they are the same.

Every Flash dev I know has run across one of these and sat scratching their head — myself included!

So what’s going on?

Well, it’s all to do with addChild()…

The Flash Bucket

Think of Flash as a bucket. When you look at a SWF, you’re looking into a container — a DisplayObjectContainer, to be precise.

To demonstrate, let’s suppose I’ve got three MovieClips (or Sprites, or Bitmaps, or whatever, it doesn’t matter), and I addChild() them to the document class:

public class DocumentClass extends MovieClip
{
	public var bigM:BigM = new BigM();
	public var bigJ:BigJ = new BigJ();
	public var bigW:BigW = new BigW();
	public var shapes:Shapes = new Shapes();
	public function DocumentClass()
	{
		bigM.x = 25;
		bigJ.x = 160;
		bigW.x = 270;
		bigM.y = 140;
		bigJ.y = 140;
		bigW.y = 140;
		addChild( bigM );
		addChild( bigJ );
		addChild( bigW );
		addChild( shapes );
	}
}

(I think you can guess which symbol has which instance name.)

When I say Flash is like a bucket, I mean it looks like this:

When you addChild() a symbol, you drop it into the bucket, and it sits slightly above everything else that’s in there. Of course, unless the objects overlap, you don’t notice this.

Buckets of Buckets

Now let’s take a look at what happens with a more complicated display object. Suppose we make a new class like this:

public class Shapes extends MovieClip
{
	public var greenTriangle:GreenTriangle = new GreenTriangle();
	public var blueCircle:BlueCircle = new BlueCircle();
	public var redSquare:RedSquare = new RedSquare();
	public function Shapes()
	{
		greenTriangle.x = 25;
		blueCircle.x = 160;
		redSquare.x = 270;
		greenTriangle.y = 270;
		blueCircle.y = 270;
		redSquare.y = 270;
		addChild( greenTriangle );
		addChild( blueCircle );
		addChild( redSquare );
	}
}

As a bucket, we can imagine that this symbol will look like this:

…but we won’t see any of this inside the SWF unless we addChild() it to the document class:

public var shapes:Shapes = new Shapes();
//...missed out some code here...
shapes.x = 0;
shapes.y = 0;
//...missed out some more code...
addChild( shapes );

Now the SWF will look like this:

…but what about in bucket view? Well, we don’t just drop each new shape into the document class bucket; rather, we drop each shape into the Shapes bucket, and then drop the whole Shapes bucket into the document class bucket:

OK, cool. Now, you can see that the M is just above the green triangle, so they should have the same x-values but different y-values, right? We can check with a trace():

addChild( shapes );
trace( bigM.x, shapes.greenTriangle.x, bigM.y, shapes.greenTriangle.y );

This returns 25 25 140 270 as we’d expect. So far, no problems.

What if we move the M to the right by 50 pixels?

addChild( shapes );
bigM.x += 50;
trace( bigM.x, shapes.greenTriangle.x, bigM.y, shapes.greenTriangle.y );

The trace() now returns 75 25 140 270 — again, just as it looks. For the sake of completeness, let’s try moving the green triangle too:

bigM.y += 10;
shapes.greenTriangle.y += 10;
trace( bigM.x, shapes.greenTriangle.x, bigM.y, shapes.greenTriangle.y );

Now the trace() returns 75 75 140 270. Great. Let’s just set everything back how it was, now:

addChild( bigM );
addChild( bigJ );
addChild( bigW );
addChild( shapes );
//no changes to any x-values

There’s one thing we haven’t tried, of course; moving the shapes object.

Stretchy Buckets

What happens if we move the entire shapes bucket 50 pixels to the right?

addChild( shapes );
shapes.x += 50;

It looks like this:

This time, the green triangle is 50 pixels to the right of the M, so presumably its x-value will be 50 bigger:

addChild( shapes );
shapes.x += 50;
trace( bigM.x, shapes.greenTriangle.x );

Hang on… the trace() returns 25 25. It says the two x-values are the same. What’s happened?

It’s easier to understand in bucket view:

It’s a little unclear, but the shapes bucket has shifted to the right, just as we told it to. This has caused the document class bucket to stretch wide enough to fit it — though note that the Flash player window still has the same view of the document class that it did before.

If you look at the shapes bucket, you can see that the green triangle is still as far away from the left-hand side of that bucket as it was before. And here’s where the confusion lies.

See, x and y are just values that say how far away an object is from the top-left corner of its parent — that is, the bucket to which the object is addChild()-ed.

Here, I’ll prove it. When you call addChild() on an object, its x- and y-values don’t change. Also, an object can only have one parent at any given time. This means we can change the green triangles parent from the shape class to the document class:

addChild( shapes );
shapes.x += 50;
addChild( shapes.greenTriangle );

The green triangle is still a variable belonging to the Shapes class, which is why we have to write shapes.greenTriangle to access it, but now we’ve changed which bucket it’s in. The SWF looks like this:

…and in bucket view, it looks like this:

The triangle’s x-value is the same as before (we could trace it and prove it) but it now refers to its distance from the left edge of the document class, rather than from shapes. Also note that it’s dropped on top of everything else inside the document class bucket.

The same applies to rotation, width and height, but they’re a little harder to visualise.

Other Affected Properties

For this part, I’m going to go back to how things were at the start, with shapes in its normal place and the green triangle inside the shapes bucket.

Also, to make things simpler, I’ll draw a border around the edge of the Shapes class so that we can see it:

public function Shapes()
{
	graphics.lineStyle( 6, 0x330066 );
	graphics.drawRect( 0, 0, 400, 380 );

(I’ve used those values because they’re the dimensions of my Flash movie.)

By default, shapes.rotation is zero, so let’s change it and see what happens:

//etc
shapes.rotation -= 10;

Not a surprising result. You probably won’t be surprised either to learn that the rotation values of each shape is still zero. Only their parent’s rotation is different.

What about the x- and y-values of the triangle now?

trace( shapes.bigTriangle.x, shapes.bigTriangle.y );

This returns: 25 270, the same as before. It’s a little odd, because the distance from the triangle to the left side of the shapes bucket actually has changed this time, if we measure horizontally:

What’s happened is, when we rotated shapes, we also rotated the x-axis and y-axis used by every child of shapes!

We say that each DisplayObjectContainer has its own coordinate system (its own pair of x- and y-axes).

So instead of thinking as the triangle’s x-value as its distance from the left edge of its parent, we should think of it as the distance from the edge of its parent along the negative x-direction. The same goes for its y-value. (Remember, in Flash, y points “downwards”. Well, until you rotate it!)

This is kind of complicated when written out in words, so I like to sketch out a picture (like the one above) whenever I get confused.

How about width? Let’s set the rotation back to normal and try changing the width instead:

addChild( shapes );
shapes.width *= 2;

Here, the circle is clearly twice as wide as it is high.

trace( shapes.blueCircle.width, shapes.blueCircle.height );

…and yet this trace returns 83 83. Once again, the shapes coordinate system has been changed; this time it’s been stretched.

If we were to now set shapes.bigTriangle.x += 1, we would actually see the triangle move two pixels to the right. So the x-value of the triangle can no longer be measured in pixels, since pixels are a property of the computer screen.

What do we call them, then? Well, they’re just “units”. Units-that-would-be-equal-to-pixels-if-everything-were-at-its-correct-size is a more accurate name, but a little unwieldy.

What To Do About All This

The simplest way to avoid getting in a big mess is to make sure every single object we’d ever want to refer to in code has the same parent: the document class. That way, if two objects have the same x- and y-values, we know they are in the same place, because they must be using the same coordinate system.

Of course, this is ridiculously inconvenient. Fortunately, we can get the benefits of a shared coordinate system without the drawbacks.

There is a function, localToGlobal(), that will take the x- and y-values of a point in one coordinate system, and return the x- and y-values of the same point in the document class’s coordinate system.

What? OK, here’s an example. Suppose I move the shapes over to the right:

addChild( shapes );
shapes.x += 135;
//no longer altering the width or rotation

Now, we know that the green triangle’s x-value is going to say the same as before — the same as the M — if we trace it. And yet, we can see that in the coordinate system of the document class, it should have the same x-value as the J. We can use localToGlobal to show this:

var triangleCoordinatesInsideShapes:Point = new Point( shapes.greenTriangle.x, shapes.greenTriangle.y );
var triangleCoordinatesInsideDocumentClass:Point = shapes.localToGlobal( triangleCoordinatesInsideShapes );
trace( bigJ.x, triangleCoordinatesInsideDocumentClass.x );

As you can see, localToGlobal is run on the shapes object, not the triangle; this is because we are converting from the shapes coordinate system.

That trace statement returns 160 160, just as we’d hope, showing that the green triangle and big J have the same x-coordinate relative to the document class.

What about the other way around? Use the globalToLocal() function. This takes a point in the coordinate system of the document class and returns the same point in any given object’s coordinate system, like this:

var bigJCoordinatesInsideDocumentClass:Point = new Point( bigJ.x, bigJ.y );
var bigJCoordinatesInsideShapes:Point = shapes.globalToLocal( bigJCoordinatesInsideDocumentClass);
trace( bigJCoordinatesInsideShapes.x, shapes.greenTriangle.x );

That returns 25 25 — again, the coordinates match, but this time they’re given relative to shapes.

If you want to compare two objects that are in different containers, but neither of them is a child of the document class, you can combine the localToGlobal() and globalToLocal() functions.

For example, here I’ll add another instance of the shapes class, but I’ll set its alpha to 0.5 so that it looks transparent:

public var transparentShapes:Shapes = new Shapes();
//...missed out some code here...
transparentShapes.x = 0;
transparentShapes.y = 0;
//...missed out some more code...
addChild( transparentShapes );
transparentShapes.alpha = 0.5;
transparentShapes.x += 135;

(Note that I’ve also moved transparentShapes to the right by 135 units.)

Here, naturally, we’d find that shapes.bigTriangle.x and transparentShapes.bigTriangle.x were equal, because we haven’t moved either triangle within its parent. But we want to show that the transparent triangle has the same coordinates as the opaque circle. We need to chain a globalToLocal and a localToGlobal command:

var circleCoordinatesInsideShapes:Point = new Point( shapes.blueCircle.x, shapes.blueCircle.y );
var circleCoordinatesInsideDocumentClass:Point = shapes.localToGlobal( circleCoordinatesInsideShapes );
var circleCoordinatesInsideTransparentShapes:Point = transparentShapes.globalToLocal( circleCoordinatesInsideDocumentClass );
trace( circleCoordinatesInsideTransparentShapes.x, transparentShapes.greenTriangle.x );

This trace gives us 25 25. Success!

What About Rotation and Width?

Rotation and width are slightly more awkward to deal with.

Rotation is just a matter of addition and subtraction. If we wanted to see what angle the opaque triangle was at in the coordinate space of the document class, we’d have to add shapes.rotation and shapes.greenTriangle.rotation. If we wanted to work out its angle in the coordinate space of the transparent shapes, we’d then have to subtract transparentShapes.rotation.

For widths and heights we have the getBounds() method. It’s used like this:

var triangleBounds:Rectangle = shapes.greenTriangle.getBounds( this );
trace( triangleBounds.width );

That’ll give us the width of the triangle in the coordinate space of the document class (because we’re writing code inside the document class, that’s what this will refer to).

Note that the format is different to localToGlobal; you call the function as a method of the object whose width you want to find out, and pass the desired coordinate space as an argument — in localToGlobal its the other way around.

If for some reason you wanted to find the width of an object apart from any lines used to draw it, you could use the getRect() method instead. It’s called in the same way.

So that’s pretty much everything you’d need to know about coordinate systems in Flash. Any questions?

Tagged as: addChild, coordinate systems, coordinates, globaltolocal, localtoglobal, rotation