How to load data from a text file into Flash using the LoadVars object

Our hangman game currently has the unstated theme of animals but we want to be able to easily change the theme (and the corresponding words to be guessed) without modifying the FLA file (and thus without using Flash). This is why we have the words to be guessed in an XML file, and now we will include a very small text file that simply contains a word describing the theme of the hangman game.

Download this file (guessword.txt) and place it in the folder where you saved your new Flash document.

If you were to open the text file (in Word or Notepad, for example), you would see the following text:
myTopic=an+animal              This will be explained later.

Now we need to add code to load the data from the text file into Flash. Select Window > Actions to open the Actions panel. Replace the following lines of code:

guessWord_txt._visible = false;
startScreen_mc.message_txt.text = "Welcome to the hangman game! To, win you must try to guess the mystery word. Press the play button below to start.";

... with these:

guessWord_txt._visible = false;
var welcomePart1:String = "Welcome to the hangman game! To, win you must try to guess the name of ";
var welcomePart2:String = ". Press the play button below to start.";
var guessTopic:LoadVars = new LoadVars();
guessTopic.onLoad = function(success:Boolean) {
if (success) {
startScreen_mc.message_txt.text = welcomePart1+this.myTopic+welcomePart2;
} else {
startScreen_mc.message_txt.text = "The data failed to load. I am sorry!";
}
};
guessTopic.load("guessword.txt");

That's all! Your movie should now display the theme as the movie starts. Try modifying the txt file and the xml file to match a different theme.

The rest of this page explains how the above code works.

The first line effectively hides the guessWord_txt text field by setting its _visible property to false. It will be made visible once the player presses the play button, the functionality of which will be defined later.

The second and the third line define the welcomePart1 and welcomePart2 variables. Both are defined as String variables, which means that they will hold text values. And these text values are assigned to them immediately. They are, respectively:

They may appear a little strange. If you look at them closely, you will see that the first one ends with a space and that the second one starts with a full stop, followed by a space and another sentence. This is because they will both be parts of the welcome message, once the game loads. The third piece of information for the welcome message will be loaded from an external text file.

The main reason for doing so is that once you finish the SWF file, with all the ActionScript code that you are going to add, you will have a completely dynamic game at your disposal. You won’t have to edit the .fla file anymore and re-export it as a .swf. If you ever want to change the topic of the game (the type of word to be guessed) and the words, all you will have to do is edit the text and XML files, upload them to your website, and that’s it! That’s a much, much better solution than cementing the values inside the Flash file and having to re-edit it every time you want to have a different game.

Suppose that you want the player to guess the name of an animal. The welcome message would be as follows: "Welcome to the hangman game! To, win you must try to guess the name of an animal. Press the play button below to start." The two bolded words, “an animal”, are placed in the guessword.txt file that you have downloaded at the beginning of this tutorial. Why both the article and the noun, and not just “animal”?

Well, suppose that you are going to change the game so that the player has to guess the name of a city. If you had put the article “an” into the code of your .FLA file, the resulting message would be “…guess the name of an city”, which is bad English. So it is logical that both the type of word to be guessed an its article should be put in the external text file. Thanks to this, you can just change “an animal” into “a city”.

And now comes the chunk of code that loads the text file and performs different actions, depending on whether the external text file was loaded successfully or not. The first line creates a new LoadVars object, which is used to load external variables into Flash or export variables to an external source:

var guessTopic:LoadVars = new LoadVars();

Like with the majority of objects in Flash, you can’t create them separately, like this: new LoadVars(). This won’t work at all. You must create a variable (guessTopic in this case) and then store an instance of the object that you wish to use inside that variable, exactly like is shown in the line of code above. Since you are creating a new LoadVars object, the type of the guessTopic variable is set to LoadVars, of course (guessTopic:LoadVars). Once you do that, for all practical purposes, you can say that the guessTopic variable is in fact an instance of the LoadVars object.

Let me show you now how to load variables from an external source (the guessword.txt file in this case) using the LoadVars object that you just created. Before loading the actual data, it is considered the best practice to tell Flash first what to do once the loading has finished, and then order it to load the data.

To do this, you must use the onLoad event handler of the LoadVars object.

guessTopic.onLoad = function(success:Boolean) {
if (success) {
startScreen_mc.message_txt.text = welcomePart1+this.myTopic+welcomePart2;
} else {
startScreen_mc.message_txt.text = "The data failed to load. I am sorry!";
}
};
guessTopic.load("guessword.txt");

So, the onLoad event handler reacts when external variables (variables stored in guessword.txt file in this particular case) have been converted into object properties. To better understand this, have a look at the guessword.txt file. Open it and look at its contents. You will see this:

myTopic=an+animal

myTopic is the name of the variable, and an+animal is its value. You have certainly noticed the plus (+) sign between these two words. It is used to denote spaces in a file that is going to be loaded via the LoadVars object. You can’t just put a simple space between the value’s words, you must separate them with a plus sign.

If you are going to create a project where you will need multiple variables with different values, your text file’s contents would look like this:

myName=John&mySurname=Smith&myAddress=Flash+plaza&myCity=Flashville&myCountry=Flashia

As you can see, the various variables with their respective values are separated by ampersand signs (&). In programmer’s jargon, these variables and their values are called name/value pairs.

I mentioned above that once loaded, these external variables will be converted into object properties. What this means is that the myTopic variable will become a property of the guessTopic LoadVars object. Thanks to that, you can retrieve the value of this variable by referencing it like this: guessTopic.myTopic. And from that, Flash would read the value, which “an animal” in this case.

Fine! Now that you understand how the LoadVars object loads external variables into Flash, let me show you how it will react once the data has been loaded. As you can see, the first line calls the guessTopic object’s onLoad event handler, with a parameter passed to it: success. This parameter is of the Boolean type, meaning that its value can be either true or false.

guessTopic.onLoad = function(success:Boolean) {
if (success) {
startScreen_mc.message_txt.text = welcomePart1+this.myTopic+welcomePart2;
} else {
startScreen_mc.message_txt.text = "The data failed to load. I am sorry!";
}
};

This parameter is necessary, because you must check if the variables have been loaded and converted into properties of the guessTopic LoadVars object. The contents of the event handler function do just that (they are located between the function’s curly braces: { and }). Here, the contents consist of an if/else conditional statement.

If the value of success turns out to be true (meaning the data has been loaded and converted successfully), the welcome message will be displayed. If it turns out as false, an error message will be displayed. In both cases, the message will be displayed in the message_txt text field, which is situated inside the startScreen_mc movie clip. In the first case (when success equals true), the message will be composed of three variables’ values:

welcomePart1+this.myTopic+welcomePart2

You have already defined and seen the values of the variables welcomePart1 and welcomePart2. The middle one is referred to as this.myTopic. The keyword this points to the guessTopic object itself, because it is written inside the object’s onLoad event handler function. And, just as I said previously, the myTopic property is the variable that has been loaded from the external text file and converted into a property of the guessTopic object. Its value: “an animal”. Without the quotation marks, of course — I have written them here to better distinguish the value from the surrounding text. So the welcome message will inform the player what is the topic of the game (an animal, a city, a car, etc).

And if the loading fails, the “I’m so sorry” message is displayed :). If the loading fails, it is basically beyond your control. The loading error could be due to the problems the player may have with his Internet connection, his firewall and so on. The best thing that you can do is to notify the player that the loading has failed.

Finally comes the line that actually tells Flash to load data from the external text file:

guessTopic.load("guessword.txt");