This article will illustrate the appropriate way to subscribe to events from an object.

There are so many AS3 examples and tutorials out on the internet that make use of the addEventListener() function. Why? It is hugely important if you plan on making anything other than an animation. In all of these examples and tutorials, very few I have seen will actually explain the appropriate way to work with events and the pitfalls if you do not use them correctly.

Following is an example of a typical use of the addEventListener() function:

someObject.addEventListener(MouseEvent.CLICK, ClickHandler);

Looks pretty simple, and really it is. This simply calls the function ClickHandler any time the user clicks on someObject. That is exactly what we want to do, so what is the big problem? There isn’t a big problem until you are done with someObject.

Lets say after you click on someObject (pretend it is a button) it takes you to another frame. someObject is no longer needed, so you remove it from the stage and the application continues on. What most examples don’t tell you is that it is extremely important to remove the click event from the object before you dispose of it or you may as well just leave the entire object hanging around in memory.

someObject.removeEventListener(MouseEvent.CLICK, ClickHandler);
someContainer.removeChild(someObject);
someObject = null;

Certainly you have seen some example of the 3 lines above. This set of lines effectively removes someObject from the stage and sets the object reference to null. Possibly the most important line is the first line and many times this line is either looked over completely or not explained well enough to illustrate its importance. To an experienced AS3 programmer, it should go without saying that you need to remove all unnecessary event listeners when they are no longer needed, however a beginner may not understand the importance.

Why is this so important? From the Actionscript 3.0 Language Reference:

If you no longer need an event listener, remove it by calling removeEventListener(), or memory problems could result. Objects with registered event listeners are not automatically removed from memory because the garbage collector does not remove objects that still have references.

What this means is that if you do not call removeEventListener() on all registered events of an object, it will not go through the garbage collector. You will have an object floating around using up memory that could have been released and used for something else. Simply setting an object to null is not enough, you must remove all event listeners before you set it to null.

This is not a fix-all for memory leaks obviously, but it is a huge pitfall that can be avoided with a little bit of knowledge and planning. I learn a lot of information by searching for tutorials and examples on the internet and have seen examples of the above situation all over. However, most will not explain the importance of event listener cleanup and how it relates to memory issues.

For what it is worth, I am aware of the “useWeakReference” parameter of the addEventListener() function. Using this in my opinion is a lazy fall back that may introduce other problems that are tough to find. Certainly there is a place where it is useful/necessary, but I don’t like to use it when you can explicitly clean up your events to ensure everything is handled appropriately.

CarzDB is a database application that stores information about a die-cast car collection. A good friend of mine has a die-cast car collection and he needed something to catalog his collection for easy reference information. We developed an application a few years ago using VB.NET 2005 for him to use and it worked great. He distributed it freely via the HotWheelsCollectors forum. We received nothing but positive feedback from all the users that downloaded it.

A few months ago we rewrote the entire program using Flex 3 and AIR to develop a cross-platform version with new features. We used the same premise of the original application in that everything possible must be customizable for the end user. Another requirement was that it must be as portable as possible. With our new build, it is more portable than before because the original version required Windows. However, now the application runs on Windows, Mac OSX, and Linux.

Being my first attempt at using Flex, I had no idea what I was in for. I have been using Flash CS3 with AS3 for about a year or so and have been able to accomplish quite a few challenges that I have attempted. My assumption was that Flex wasn’t a whole lot different from Flash… I was quite wrong and happy that I was.

Don’t get me wrong, Flash is an great authoring tool for interactive web content and will continue to be useful to me and other developers for quite some time. However, if you have a need for a database application, web or desktop, Flex provides some amazing pre-built form elements that handles working with data extremely well, far better than Flash ever could.

Although I have only just begun to work with Flex, CarzDB is a full featured database application that we intend to expand on in the future. It took a few days to become comfortable working with Flex, but after a slight adjustment period, I felt right at home. Since it is all based on the Flash Player, it uses the same syntax as Flash (Actionscript 3) so it was very easy to work with for me. I still don’t fully understand all of the “new” functionality that Flex provides (such as states), but I was able to accomplish everything that I needed to develop this application.

One thing I was not able to figure out (and still haven’t) was how to bind a database result to a tree view and have it display in a hierarchical manner. I ended up reading the result into a custom built array (which takes some time for large result sets) and applying the resulting array as the data bound to the tree view. The ideal solution is to take the result set and simply bind it to the tree view and then somehow program the tree view to display the hierarchy that I want. If anyone knows how to do this, please, please, please let me know .

Aside from that one hang up, I am quite pleased with the outcome of the application and how easy it was to develop using the Flex Framework and components that come with it. If you have a die-cast collection, check out the application and see if you can’t make use of it. The old version is available for free, but we are selling the new version for a small price of $20 per copy. There are no recurring fees to use the software. There are tons of screen shots in the documentation section of the CarzDB website. Let us know what you think!

Although there are a few different screen caliper type of programs, we wanted to create our own so we could make it do exactly what we wanted (and more). The features that we added that may be different from some of the other caliper programs are the ability to have multiple line segments on-screen at once, measure diagonal distances with the ability to see the horizontal and vertical delta measurements, display angle measurements, set a custom scale factor, and others.

If you are interested, you can download it for free by visiting the Screen Scales Project page.

Some day I will get around to posting about some of the things we did to make it work the way we wanted it to.

Reading from an XML document provides us with a lot of different abilities. First off, you can modify an XML file easier than a Flash file because you don’t have to recompile it. Second (and more importantly in my opinion), XML files can be the dynamically creating using PHP which means you can pull data directly out of a database.

Lets get started looking at the Actionscript 3 code.

1
2
3
4
5
6
7
8
9
10
11

package {
  import flash.display.MovieClip;
  import flash.events.Event;
  import flash.net.URLRequest;
  import flash.net.URLLoader;
 
  public class xml_example extends MovieClip {
 
    public function xml_example():void { }
  }
}

Above you see the bare bones of a class called xml_example. The first thing to point out is the two import statements that are necessary to read an external XML file (flash.net.URLRequest and flash.net.URLLoader). Of course you will need the typical MovieClip and Event imports as well.

9
10
11
12
13
14
15

public function xml_example():void {
  var loader:URLLoader = new URLLoader();
  loader.addEventListener(Event.COMPLETE, xmlLoaded);
  loader.load(new URLRequest("example/file.xml"));
}
 
private function xmlLoaded(e:Event):void { }

This is our constructor function. What we see here is a new URLLoader object created (called loader). Then we apply an Event Listener to it so we know when the file has been loaded (Event.COMPLETE) and where it should continue processing (the xmlLoaded function). And finally we tell the loader object to load a file using a new URLRequest object pointing to the file.xml file located in the example folder.

After all of this code has executed, and the COMPLETE event has been dispatched, we continue processing in the xmlLoaded function.

15
16
17
18
19
20
21
22
23
24
25
26

private function xmlLoaded(e:Event):void {
  var xml:XML = new XML(e.target.data);
  var posts:XMLList = xml.post;
  var i:uint = 0;
  var c:uint = posts.length();
 
  e.currentTarget.removeEventListener(Event.COMPLETE, xmlLoaded);
 
  for (i = 0; i < c; i++) {
    trace(posts[i].title.text() + ": " + posts[i].short.text());
  }
}

Finally, here is our function that processes the xml file after it has been loaded. First we create a few objects. The XML object (named xml) is where all of our data is stored which is pulled from the target of the event (our URLLoader object from the previous function). The posts object is an XMLList that is very similar to an array. We selected the post property of the XML object which represents all of the data within our xml file between the <post> and </post> tags.

After we have all of our data into usable objects, it is as simple as iterating through an array to access the data within these objects. We use a counter variable (i) and a limit variable (c) to step through the posts object and trace out the contents. You access the data by using the same property name as is in the xml file. Then call the text() method to extract the text. Obviously you would probably do something a little more exciting than simply tracing the data, but for this example it will suffice.

Following is what a sample xml file might look like along with the output that we would expect to see from our trace functions.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

<?xml version="1.0" encoding="iso-8859-1"?>
<posts>
  <post>
    <title>Sample Post 1</title>
    <short>Sample short description for the first post.</short>
  </post>
  <post>
    <title>Here is Title 2</title>
    <short>This is the second post and this is what it is about...</short>
  </post>
</posts>
 
------------  Output ------------
Sample Post 1: Sample short description for the first post.
Here is Title 2: This is the second post and this is what it is about...

This is a simple way to read data into flash using Actionscript 3. I have used it for many different things such as slide shows where the image path and caption are saved in xml and even in a database. There is more that you can do with this such as listen for incremental events triggered by the URLLoader object which allows you to create a progress bar, but I have never needed to do this as the files that I have loaded are typically small usually containing index type of information.

Check back in the future, I may add a second part to this tutorial to experiment with the progress bar.

Take Care! Wayne

Forget game play and what makes a game fun for now. This post will be focusing on things that drive players away from what could have been a great game and elements you must include in all games no matter the genre.

Don’t do These

There are a few different things that I find rather annoying while playing some games that typically drive me away from them never to return. These are things that you should avoid at all costs. Notice I didn’t say “attempt” as these are all things that can be completely avoided or at least re-worked.

Sound
First of all, sound is not required, however it can and does enhance a decent game dramatically. So, don’t forget about adding sounds to your game where applicable. If you do include sounds, always (and I mean always) at least give the player the option to mute all game sounds including background music and make it easy to do. There is nothing worse than hunting around for the mute button because you are listening to your favorite song. It is even worse (in my opinion borderline unplayable) if there is no mute option.

Advertisements
Advertisements are a great way to monetize your hard work programming and I completely support them in most cases. Although the few games that I have published only make me pennies a day so far, I still think this is a good way to make money from your games. I don’t mind seeing an advertisement for 10 seconds while the game is downloading to my cache, but don’t add advertisements in the middle of the game. Ads that show up in between levels are fine if they show up every once in a while, but if a level only takes a minute or two to complete, don’t show me an advertisement between every level. If I beat the first level or die rather quickly and an ad shows up before I am able to try again, it is almost always an immediate browser back button.

Mouse vs Keyboard
It doesn’t matter which input method your game uses, but if it relies on one and not the other, never require the player to use the second one. For example, if your game utilizes the keyboard for controls, never require the player to click with the mouse to start the next level. Provide a key they can press to go to the next level as well This is another one of those things that may cause me to go for the browser back button, though it isn’t necessarily an immediate response.

Do These

On the other side of the coin are the things that players expect out of games. These are things that should be included in all games no matter what.

Obvious Hot Spots
If your game requires a menu or buttons to move between different screens, make them visible and rather obvious that they are there to click on. Similar to the way web pages are designed, links are typically a color that stands out (in fact you have to do extra work to make links not look like links), it should be obvious to the player that the start button is the big red button that says Start. Of course your buttons can still look nice without being an eye sore, but use consistency.

Provide Instructions
Even though I typically never click the “How to Play” links found in many games, I do like to know that it is available if I need it. Usually my progression in games is to hit the Play or Start button to get going right away. You can usually figure out what to do by just jumping in and even if not, you should be able to get a feel for what the game is about. If I am even mildly intrigued, I will go back and read up on how to play. Just make sure it is available unless it is brutally obvious what to do.

Presentation
Spend some time and make your game look like you are proud of it. Whether your game features stickmen in a black and white world or professional level graphics, it is possible to make your game look good. You don’t have to be a graphics artist to make your game look decent. Follow a theme or at least be consistent and you will do yourself and your players a favor.

These are just a few things that all developers should consider when creating flash games for the public to play. Remember, if you plan to monetize your games, it is the players that will be your source of money so keep them happy.

Play a perfect remake of the classic 80’s DOS game originally created by Scott Miller of Apogee Games. Talon Designs created a flash version able to be played without the need for DOSBox.

Controls:

Cheats:

Secret Mode:
By typing “X” at the select game screen, you are entered into a “Secret Game” mode. Once in secret mode, there are two things you can do during gameplay.

Shift + 0 = Replenish Items (Gems, Whips, Teleports & Keys)
Shift + 9 = Advance 1 Level

Talon Designs God Mode:
If at the select game screen, you hit “CTRL+Shift+~” this will enable a “god” type mode, that was not available in the original game. With GOD mode enabled, there are many things you can do during gameplay.

1 = Gems + 100
2 = Whips + 100
3 = Teleports + 100
4 = Keys + 100
5 = Whip Power + 1
8 = Previous Level
9 = Refresh Current Level
0 = Next Level

About Kingdom of Kroz

Kingdom of Kroz was originally created back in the 1980’s by Scott Miller. The game was developed to run on DOS using only alphabetic graphics. It was a great game (and still is) back when there were no such thing as 3D processing power available to consumers.

Until now, Kingdom of Kroz could only be run using a program called DOSBox which emulates a DOS window. We used this program extensively to recreate the game as closely as we possibly could to the original.

This game is completely playable, though it is only about 95% complete. The highs scores table does not work and there may be a few things in the original that we missed. Kingdom of Kroz was the first of seven different adventures. We originally planned to create all of the episodes, but the initial interest when we released it back in August (2008) was not enough to compel us to spend the time creating the rest of the episodes. If there is a new found interest in this game, we may consider completing the project adding the next 6 adventures.

When we built the game, we basically built an engine for the game in such a way that none of the levels are compiled into the swf file. All of the levels are loaded from external xml files. We decided to build it this way, not because it would be easier (though it may have been), but because we wanted the ability to create our own levels just for fun. Again, we have not spent very much time at all on any custom levels, but know that it is possible if you are interested in doing so.

We hope you enjoy playing, and let us know what you think!

• read from an external xml list
• size independant
• ability to change the speed
• customized right click menu

Lets get started!

I am assuming you know enough about Flash to be able to create your project files and store them in an appropriate directory. If not, please visit the Flash Basics post.

You will need two files for this project:

• Blank Flash (.fla) file
• Actionscript (.as) file

In the .fla file set the Document class to the name of the class you will be using (my example is slideshow. The stage dimensions and background color don’t really matter for this project, but you can set them to whatever you like.

Once you have set up the Document class in the .fla file, the rest of the work will be completed in the .as file. Create the structure of the .as file as seen below.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

package {
  import flash.display.*;
  import flash.events.*;
  import flash.utils.*;
  import flash.net.*;
  import flash.ui.*;
  import caurina.transitions.*;
 
  public class slideshow extends MovieClip {
    private var clock:Timer;
    private var speed:Number;
    private var imgs:Array;
    private var imgIndex:Array;
    private var index:Number;
    private var loader:URLLoader;
 
    public function slideshow():void { }
    private function init():void { }
    private function indexLoaded(e:Event):void { }
    private function loadImage(file:String):void { }
    private function imageLoaded(e:Event):void { }
    private function nextImage(e:TimerEvent):void { }
  }
}

Now for the details…

Imports (2 – 7):

• display, events – common MovieClip imports
• utils – needed for the Timer
• net – needed for the xml functions
• ui – needed for the custom right click menu
• caurina functions are a custom package called Tweener. This package is a great open source way to create custom tweens in your projects without having to use the time line. You can download it here: http://code.google.com/p/tweener/

Variables (10 – 15):

• clock – the timer used for the transitions
• speed – the length of time an image is displayed
• imgs – a MovieClip array holding all of the images after they have been loaded
• imgIndex – an Array made up of the relative path to where the images are stored
• index – identifies the currently displayed image by its index in the imgs array
• loader – the URLLoader object we will use to load the xml index

slideshow() – Constructor Function

public function slideshow():void {
  var mnu:ContextMenu = new ContextMenu();
  mnu.hideBuiltInItems();
  var item:ContextMenuItem = new ContextMenuItem("© LittleArea");
  mnu.customItems.push(item);
  this.contextMenu = mnu;
 
  init();
}

The first five lines create the custom right click menu and remove the default menu items. All we need to do is create a new ContextMenu object. Then we call hideBuiltInItems() to remove all of the default menu items (zoom, quality, etc). There are a few that remain that we cannot remove (to my understanding). Create a new ContextMenuItem and send it the text that you want to display. Then push the new item into the customItems array and assign this.contextMenu to the new new menu. You can add event listeners to the custom items to navigate to a website or interact with your application if you would like to. After we are done with the custom menu, a call to init() will kick off the rest of the loading.

init()

private function init():void {
  imgs = new Array();
  imgIndex = new Array();
  index = 0;
  clock = new Timer(5000);
  clock.addEventListener(TimerEvent.TIMER, nextImage);
 
  var filename:String = "index";
  var paramObj:Object = loaderInfo.parameters;
  filename = String(paramObj['index']);
 
  var url:URLLoader = new URLLoader();
  url.addEventListener(Event.COMPLETE, indexLoaded);
  url.load(new URLRequest(filename + ".xml"));
}

The first four lines just initialize some of the variables and objects used and set some default values where applicable. The 5th line adds the TIMER event listener to our clock.

The filename variable is used to pull the name of the xml file that we are wanting to load. In the HTML document, you will add the name of the xml file on to the swf file name so we know which index to load. (ex: “./slideshow.swf?index=xmlfile”) Using the loaderInfo.paramaters array, we can find out what the file name of the xml file is. This will allow us to use the same swf file to load different xml files. This can even be done on the same page multiple times.

The last three lines use the URLLoader class to load the xml file we identified above. You must also add an event listener to process the file after it has been completely loaded. Also, don’t forget to append the .xml onto the filename variable.

indexLoaded(e:Event)

private function indexLoaded(e:Event):void {
  var xml:XML = new XML(e.target.data);
  var img:XMLList = xml.image;
  var i:uint;
  var c:uint = img.length();
 
  e.currentTarget.removeEventListener(Event.COMPLETE, indexLoaded);
 
  speed = xml.speed[0].text();
  clock.delay = speed * 1000;
  for (i = 0; i < c; i++) {
    imgIndex.push(img[i].text());
  }
 
  loadImage(imgIndex[0]);
}

This function is called after the xml index file has been completely loaded. We will use the XML object to pares the index file to read the necessary data. Using the event object we get from the URLLoader, we assign our XML object to e.target.data which is what we are after. i and c are temporary variables used for looping through our xml data.

Our xml file will be structures as follows:

<?xml version="1.0" encoding="iso-8859-1"?>
<images>
  <speed>5</speed>
  <image>images/img1.png</image>
  <image>images/img2.png</image>
  <image>images/img3.png</image>
  <image>images/img4.png</image>
</images>

We will read the speed from the xml file and multiply it by 1000 to roughly represent seconds. In our example there will be approximately 5 seconds between each image. You read from an XML object as if it was an object full of arrays correlating to the tags in your xml file. Set the clock delay speed to our new value.

Now, using a XMLList object, we can loop through all of the image entries and store the path in our imgIndex array. You can use relative or absolute paths in your xml file. The path should be relative to the HTML document where the swf file is embedded (not relative to the swf file itself). Once we finish looping through the list of images, call the loadImage() function and pass the first image path.

loadImage(file:String)

private function loadImage(file:String):void {
  var loader:Loader = new Loader();
  loader.contentLoaderInfo.addEventListener(Event.COMPLETE, imageLoaded);
  loader.load(new URLRequest(file));
}

The loadImage function simply creates a Loader object to load the image specified by the file parameter. Add an event listener to the Loader object (via the contentLoaderInfo property) so we know when the image has completed loading. Once this event fires, we end up at imageLoaded().

imageLoaded(e:Event)

private function imageLoaded(e:Event):void {
  e.currentTarget.removeEventListener(Event.COMPLETE, imageLoaded);
  imgs.push(new MovieClip());
  imgs[imgs.length - 1].addChild(e.target.content);
  addChild(imgs[imgs.length - 1]);
 
  if (imgs.length == 1)
    imgs[imgs.length - 1].alpha = 1;
  else
    imgs[imgs.length - 1].alpha = 0;
 
  if (imgs.length >= 2) clock.start();
  if (imgs.length < imgIndex.length) loadImage(imgIndex[imgs.length]);
}

After an image is fully loaded we end up at the imageLoaded() function. We first push a new MovieClip into our imgs array and then add the image to the newly created MovieClip object. You accomplish this by pulling the content from the target of our event (the contentLoaderInfo from the loadImage function). Then we add the MovieClip containing the image to the stage.

After this is complete we set the alpha value to 1 (fully visible) if it is the first image loaded (we know this by the length of the imgs array). If it is not the first image, we make it invisible (alpha = 0).

We start the clock if there are at least 2 images in the imgs array so the images will start to cycle.

Finally, if we haven’t loaded all of the images yet, call the loadImage() function with the next file that hasn’t been loaded yet.

nextImage(e:TimerEvent)

private function nextImage(e:TimerEvent):void {
  Tweener.addTween(imgs[index], {alpha:0, time:2, transition:"linear"});
  index++;
  if (index > imgs.length - 1) index = 0;
  Tweener.addTween(imgs[index], {alpha:1, time:2, transition:"linear"});
}

This function is fired every time our clock ticks after it has been started (in this example, every 5 seconds).

First we fade the current image out (this is known from the index variable). To use Tweener, all you have to do is call the addTween() function with the object you are wanting to tween and a custom object with all of the necessary parameters. In this case, we want to fade the MovieClip in the imgs array at the current location of index. Then we build the object to tell Tweener what to do. We want to set the alpha to 0; we want it to take 2 seconds; and we want to use the linear transition method. This is a very basic use of the Tweener class. If you would like to know more about it, please see the documentation located here: http://code.google.com/p/tweener/

After we have started the fade out tween, we set the new current index to the next image. Check to see if we have passed the end of the array and start back over at 0 if we have. Then, follow the same steps above to add another Tweener function to the new image to make it fade in.

Tweener runs both of the functions at the same time so it appears as if one image is fading into another instead of one fading out and then one fading in.

That’s all there is to it. Obviously there is more that could be added to this application (and maybe we will add on to it in another tutorial), but it works as-is as a very simple flash slide show.

Adding to your HTML page

To complete the whole project we need to add it into our HTML page. There are a few different ways to embed it, but I will only show the simplest way.

<embed 
  src="slideshow.swf?index=index1" 
  wmode="transparent" 
  scale="noscale" 
  salign="tl" 
  quality="high"
  pluginspage="http://www.macromedia.com/go/getflashplayer" 
  type="application/x-shockwave-flash" 
  width="400" 
  height="300">
</embed>

As you can see the src tag will load slideshow.swf and the xml file it will load is called index1.xml. There are a few important tags that are worth noting:

• wmode=”transparent” – this will make the background transparent so if the images are not all the same size, there will not be a solid background anywhere
• scale=”noscale” – this prevents the flash movie from scaling, it will be stretched to the size that you specify in the height and width tags
• salign=”tl” – this tells the movie to anchor itself to the top left corner instead of centering by default

The above tags is how we tell the movie to be a specific size instead of the size set by the stage.

That is a rather long and detailed tutorial, but I hope it is helpful to someone. I will add download links to a completed swf file as well as the Actionscript file.

Time for a disclaimer…
I do not consider myself an expert in this subject, as I am still learning what the capabilities are for the different technologies available. Everyone can always learn something new about anything. There is always more than one way to tackle a problem and my way may not the best or fastest, but it is how I accomplished the end result.

That being said, please feel free to comment and share your prospective, but please keep it constructive and civil so we can all learn from the community.

As for the content and the output of the projects posted on this site, everything (unless explicitly noted) is free to use as-is with the exception to the games*. All source code can be modified, changed and hacked in any way. Use these files and source at your own risk, as I will not take any responsibility for anything that happens to your site from anything downloaded from this site.

I hope you enjoy the site and find some useful information.

*All of the games posted on this site are property of the respective owner. Many of the games will not be created by myself, so please respect the rights of those that have created them for our enjoyment.