{ P I X E L W E L D E R S }

A few people have asked me to release the code to my FIVe3D Text Cloud example, so I’ve cleaned things up to the point where I wouldn’t be completely humiliated to release it into the wild. However, I thought I’d touch on a couple points and turn this post into something halfway between a tutorial and an exhibition.

If you just want the source code, you can download it at the bottom of the page. If you’d like the whole shebang, pray read on.

The (new and improved) example:

FIVe3D Basics

FIVe3D is ridiculously easy to set up. In this example, I used the following code to set up everything I needed:

// the Scene3D class is what contains and renders everything else
// think of it as a 3D Stage class
scene = new Scene3D();
scene.x = 375;
scene.y = 200;
addChild( scene );
 
// Sprite3D is, obviously, a 3D version of the standard Sprite class
// it is an actual DisplayObject, so you can use normal positioning, filters, etc. on it
container = new Sprite3D();
scene.addChild( container );

You’ll notice that the syntax is just like AS3 extended into the third dimension. You can nest Sprite3Ds just like Sprites. When you move or rotate the parent Sprite3D, the children will move and rotate with it. The reason I’ve created a container Sprite3D here is so I can rotate several children at the same time.

Now if I wanted to do this the easy way, I could just add my text in one big chunk with the DynamicText3D class that ships with FIVe3D. It works much like the AS3 TextField class, except that the fonts are actually ActionScript files (you’ll see what I mean when you crack open the FIVe3D source).

var txt:DynamicText3D = new DynamicText3D( HelveticaBold ); // HelveticaBold ships with FIVe3D
txt.size = 30;
txt.color = 0xD34328;
txt.text = "Pixelwelders LLC"
container.addChild( txt );

That’s it. The Scene3D class takes care of its own rendering, so you don’t have to trigger it yourself, Papervision-style. Even when a FIVe3D scene looks static, it is actually rendering at your current frame rate. Thus, this is enough code to render 3D text in FIVe3D. Add an ENTER_FRAME listener and increment the container.rotationX property every frame and you’ll see what I mean.

Moving On…

Now this is fine for your everyday run-of-the-mill 3D text, but not for the effect that I had in mind. If I had added my text this way, it would have behaved as a single block, each letter forever doomed to stay wedged firmly between its neighbors. No, I had bigger plans for this text.

For this effect, I created a class called MotifCollection3D. Not a very good name, but typography is not my strong suite and I wasn’t quite sure what else to call it. It’s an extension of the aforementioned FIVe3D Sprite3D class, and it contains one DynamicText3D instance for every letter of the word that it’s currently displaying. This is how you instantiate it:

var cloud:MotifCollection3D = new MotifCollection3D( "PIXELWELDERS LLC", HelveticaBold, 30, 0xD34328 );
container.addChild( cloud );

There’s nothing to it. You send the text, the font class (again, included with FIVe3D), the size, and the color. It creates and assembles all the DynamicText3D instances, and then you can treat it like any other Sprite3D. However, it also includes two methods: assemble(), and the thrillingly-named explode().

Calling either of these methods cycles through all the instances of DynamicText3D and tweens them each to a destination using TweenLite. The explode() method was easy: it just chooses a random destination and rotation for each letter. The assemble() function, on the other hand, was a bit trickier; it needs to know the exact width of every letter in order to place them next to each other.

Happily, that is one of the things that’s included with the FIVe3D typography classes. Each letter, number, and punctuation mark in HelveticaBold contains a __width property, accessible like so:

var letterWidth:Number = HelveticaBold.__widths[ "P" ]; // returns the width of the "P" glyph

That’s a start, but it returns the same width regardless of what size the font is being displayed at. After a little experimentation, I found that this code gives the correct glyph width no matter what size the font:

var letterWidth:Number = HelveticaBold.__widths[ "P" ] * ( size / 100 );

I think that pretty much covers anything novel that I may have done. There are additional comments in the code as well, and it’s only two classes anyway: it shouldn’t be too difficult to figure out anything not explicitly laid out here.

Download Source

Pixelwelders FIVe3D Text Cloud

NOTE: You’ll need to download TweenLite and FIVe3D from their respective sites to get this to run. But you probably already knew that.

What is a Singleton?

A) In poker, a card that is the only one of its rank.
B) In animal husbandry, the sole surviving offspring of a litter.
C) In astrology, a single planet alone in a hemisphere (or some crap like that).
D) In mathematics, a set with only one member.
E) In England, a small village about 7 miles north of Chichester in West Sussex.

All of these things share a trait, and that trait is that each is the only one of its kind. If two kittens survive from a litter, neither one is a singleton. If a set has more than one number, it is not a singleton. In works the same way in object-oriented programming; a Singleton is a class that allows only one instance of itself; if there are more than one, that class cannot be a Singleton.

So why would one want a class that only allows one instance of itself? I can think of many applications. A ScoreKeeper class for your game, perhaps, or a Countdown class that keeps track of how much time you have to complete a level. In OS Wars I use a Singleton to keep track of all building resources currently in the game. There’s another one that keeps track of all the units on the battlefield. In fact, the Battlefield itself is a Singleton, because there’s no reason I would ever need more than one.

Another great thing about a Singleton is that, because there is only one, it’s very easy to get to. With a normal object, you have to worry about passing it around to the various classes that might need it. With a Singleton, that’s not necessary. All you need to do is import the class and voilà- there’s your Singleton.

It works this way because the class itself keeps a static reference to the only instance of itself. So instead of calling the constructor to get a reference to a new instance, you call the SingletonClassName.instance method to get a reference to the already-created instance. If that doesn’t make sense, here’s an example. This first piece of code is what a normal ScoreKeeper class would look like. With this structure, you can use that syntax that everyone knows and loves, new ScoreKeeper(), which returns a brand new ScoreKeeper every time it’s called.

package
{
	public class ScoreKeeper
	{
		public function ScoreKeeper()
		{
			trace( "new ScoreKeeper" );
		}
	}
}

But suppose you wanted to ensure that there was only one ScoreKeeper, and you wanted to be able to easily access it from any location in your program. That means two things: A) the constructor can only be called once, and B) you need to keep track of the new ScoreKeeper that one time the constructor does get called. What good is having one instance of a class if you can’t get to it? So here’s the Singleton version of the above class:

package
{
	public class ScoreKeeper
	{
		private static var _instance:ScoreKeeper;
 
		public static function get instance()
		{
			if ( !_instance )
			{
				_instance = new ScoreKeeper();
			}
 
			return _instance;
		}
 
		public function ScoreKeeper()
		{
			trace( "new ScoreKeeper!" );
		}	
	}
}

There are two differences here: the static variable _instance and the static method get instance(). The _instance variable is where the actual instance of this class is stored. And the get instance() method, of course, enables you to access this instance. So to access this Singleton, you would use:

ScoreKeeper.instance;

And to call any methods or properties of the Singleton, you would use this syntax:

ScoreKeeper.instance.addScore( 50 );
trace( ScoreKeeper.instance.score );

This of course assumes that your class has a public method called addScore() and a public property called score. You can get to any public methods or properties this way.

This also adds one more layer, called lazy initialization. Look in the get instance() method, and notice that before it returns a reference to the Singleton, it checks to see if that reference exists. If so, it simply returns it. If not, it creates it first and then returns it. Either way, you’re guaranteed to get the one existing instance.

There is one problem remaining- if you were so inclined, you could still call the constructor without going through get instance(), which would of course result in two Singletons. And as we discussed above, making two of something makes it not a Singleton anymore. So how can we prevent this? There are a few ways I’ve seen floating around, but the simplest is this:

package
{
	public class ScoreKeeper
	{
		private static var _instance:ScoreKeeper;
 
		public static function get instance()
		{
			if ( !_instance )
			{
				_instance = new ScoreKeeper();
			}
 
			return _instance;
		}
 
		public function ScoreKeeper()
		{
			if ( _instance )
			{
				throw new Error( "Singleton already exists- use get instance() to access" );
			} else {
				trace( "new ScoreKeeper!" );
			}
		}	
	}
}

The new lines are in the constructor. The get instance() method still only calls the constructor once, but if you forget it’s a Singleton and call the constructor later, you get a runtime error.

There are also a couple more complicated ways of ensuring that your Singleton is in fact a Singleton, but I haven’t lost too much sleep over over it. I usually even leave out the check in the constructor. Just remember that if it has _instance and get instance(), and a big comment up at the top that says “SINGLETON!”, it’s probably a Singleton.