Home / Developer Center / Director Developer Center /

Director Article

Joe Sparks
joesparks.com

This is the second part of the article Dynamic Run-time Linking to External Media with Director MX. If you haven't already, you should read that article first. This tutorial discusses methods for creating new cast members "on the fly" using external media. Although you can link to external media directly, the strategies described here are useful for handling a large number of external members. By creating new cast members and linking in the external media on demand, you can decrease the file size and increase the performance of your Director movie.

Sample Files
Before you begin, download the sample files for this tutorial:


Windows		Macintosh
	external_media.zip (282K)		external_media.sit (285K)

An example of this technique is displayed in the Shockwave movie below. Try clicking on the list of external file names to see the cast members appear. This Director movie contains only one bitmap member in the cast and a few scripts and UI elements. One field in the Director movie holds a list of the external files and the files themselves are located in a folder in the same directory as the DCR file (shockwave movie file). This movie allows you to import a file from the list into the movie, simply by clicking on its name. Click each file name until you have imported all of the files in the list:

To view this demo, you need the latest version of the Macromedia Flash Player.
Download the free Macromedia Flash Player now.

Using an External Text File as a Media Menu
Now that you've had a chance to see this technique in action, it's time to take a look under the hood and see what's going on. First, we'll examine the contents of the text file named medialist.txt. (This file is located in the "external_media" folder of the downloadable sample files, if you'd like to open it and review the file.)

The text file looks like this:

@/media/ 

                            Blue_JPEG.jpg, #bitmap 

                            Hello_JPEG.jpg, #bitmap 

                            HI_PNG_32.png, #bitmap 

                            I_am_GIF.gif, #bitmap 

                            Pink_JPEG.jpg, #bitmap

                            I_Am_Flash.swf, #flash 

                            sf_sky.jpg, #bitmap 

                            SF_Sunset.jpg, #bitmap

                            joes_rddbook.jpg, #bitmap

                            bird.jpg, #bitmap

                            BDalpe.jpg, #bitmap 

                            ScaryBarrie.jpg, #bitmap

This external text file contains the list of media (files in the media folder) which are available to use in the Director movie. The movie is scripted to download the text file "medialist.txt" as it starts playing. This text file determines the list of "potential cast members" that are displayed in the left column of the movie. After each filename, there's an indicator (beginning with the # symbol) specifying the type of cast member to create for each media file. This is important, because the media files must be created as the corresponding file formats, or they will not work. For example, a SWF file (Flash movie) must be added to the cast as a Flash file, not as a bitmap file.

This tutorial uses an external text file for the sake of simplicity. However, it is important to note that the list of potential cast members (the available external media files) could come from anywhere. The data could exist in a database, and you could use Lingo to connect to a server and download the list as the movie starts. Or, if you are creating a presentation for a kiosk (with a finite amount of media), you could include the full list of external media files within the Director movie itself. In this example, the external text file is used because you can easily update the file, upload the new version to the server, and the existing Director movie (DCR file) will display the new version of the text file. This is very convenient strategy for updating existing director projects.

Let's try this now. Launch Director MX. Then, open the Director movie CreateAsNeeded.dir. Play the movie in authoring mode to see the same functionality as shown in the Shockwave movie at the beginning of this article. Then, stop the movie.

Open the text file "medialist.txt", which is located in the "external_media" folder of the downloadable sample files. Add this line after the last line in the list:

JoeFococcia.jpg, #bitmap

Save and close the text file. Then, play the Director movie again.

You should now see the item "JoeFococcia.jpg" appear at the bottom of the list of potential cast members in the movie. (This particular JPG file is included in the "media" folder with the other media files, and adding the name and file type to the text file makes if possible for the Director movie to access it). Stop playing the movie when you are finished.

At this point, if you like, you can add your own files to the media folder. This movie was designed to hold elements that are 128 x 128 pixels in size. After cropping the files (if needed) and copying them to the media folder, simply add the file names and the file types to the medialist.txt text file. Save and close the text file, and then play the movie in Director. You'll see your files appear in the list, and if you click the file names, the image files will display in the movie.

Preloading the External Media Before Creating a New Cast Member
In order to ensure good performance in your Director movie's playback, you need to add some code to your movie that verifies that the external media is available to the movie before attempting to display it. When creating a Shockwave movie, this step is critical. This example uses the net lingo command preloadnetthing with loop scripts that continually check the status of the download. The script waits until the requested file is completely downloaded before assigning its file name to a new cast member in the movie. The net lingo command works fine offline (locally) too, so the same Director movie will work when played on a hard drive, in a projector situation, as well as when downloaded from the Internet.

The process of checking to see if the elements have loaded (before they are utilized) is comprised of two steps:

Step One:
The following Lingo command initiates the download of the external media item. The status of the download is stored and updated in the global variable gNetID.

gNetID
                                = preloadNetThing(directorypath/something.jpg)

Note: Rather than using gNetID, you could rename the variable anything you'd like. The important thing is to make sure that you declare this global variable at the top of your script. For example, you could declare

global
                            gMyVariableName

instead of

global
                            gNetID

, if you prefer to follow a different naming convention. Of course, if you choose to use a different variable name, be sure to update every instance of the variable in the sample movie so that the variable remains consistent.

Step Two:
This part involves periodically checking on the status of the download. When the script returns the status that the file has finished downloading, then it allows the movie to display the file. The script below is taken directly from the sample movie CreateAsNeeded.dir. This script is called when the playback head encounters a frame script that calls it. If the media element is not yet finished downloading, the script loops back to the same frame, and calls the script again.

--
                                This script is called from a frame script, to
                                check

                            -- on the progress of the file being downloaded.

                            on waitForExternalItemToDL

                            -- Note that this script is
                            not doing error checking

                            -- tError = netError(gNetID)

                            -- put tError

                            -- MAIN PART: checking to set if file is ready to
                            be used:

                            if netDone(gNetID) then

                            -- The download is done, so
                            now it's time to create a new

                            -- cast member (by calling custom handler):

                            createNewMember

                            -- And then call a sprite display
                            handler:

                            PrintASprite gCurrentExternalMediaL

                            -- This advances the playback
                            head from the "waiting" frame of 

                            -- the score, to another frame that allows the user

                            -- to pick a new file (this script only allows one
                            download at a time):

                            go "PickFiles"

                            else

                            -- looping back to a marker
                            in the score (which is preferable,

                            -- instead of looping on a single frame)

                            go "DownloadingItem"

                            end if

                            end

Using the New() Command to Create New Cast Members
Let's look at the Lingo Dictionary listing for the New Cast member command:

new()

                            Syntax

                            new(type)

                            new(type, castLib whichCast)

                            new(type, member whichCastMember of castLib whichCast)

                            variableName = new(parentScript arg1, arg2, ...)

                            new(script parentScriptName, value1, value2, ...)

                            timeout("name").new(timoutPeriod, #timeoutHandler,
                            {, targetObject})

                            new(xtra "xtraName")

As you can see, the New() command can be used in a variety of ways to create new cast members (and many other things) from Lingo on the fly. Here's how the New() command is used in this example:

tMember
                                = new(tType, castLib gImportCastLib)

In the code above, tMember is the variable that will hold the resulting location of the new cast member (member number and castlib name). This information is returned by Director, after the new member is created.

The variable tType contains the cast member type to create (in symbol form). In this example, the type of cast member is either #bitmap or #flash. The type information is already defined in the medialist.txt text file. If you prefer, you could use other strategies for assigning the corresponding type of file to each media element. For example, you could use Lingo scripts to parse the file name for the extension, or you could create an interface element for the movie and require that the user selects the appropriate type, and so on.

As mentioned previously, it is very important to create the right kind of cast member to contain your external media file! If you try to set a #bitmap type to a .swf file, it won't display. The type has to match up with the supported external file—and in the case of a .swf file, the type would be #flash.

The variable gImportCastLib holds the name of the castlib where the new member will be created. In this example, it is the second castlib. Whenever you are creating and destroying dynamic cast members, it makes it easier if you create a blank, free cast library reserved for this purpose. By specifying a different cast library, you can ensure that new cast members won't accidentally replace the existing cast members needed for your main movie.

Assigning a File Name to the New Cast Member
The last step of dynamically creating cast members involves setting the filename property of the new cast member. In this example, the Lingo code looks like this:

tMember.filename
                                = gCurrentExternalMediaL.fullpath

The line of code above might be difficult to understand, because the real values are obscured by the variable names. Let's take a look at the same line of code, but this time the variables are replaced with the actual values:

member(
                                1, 2).filename = "@/media/photo.jpg"

Now it is much easier to see what is happening. You may remember this command from the beginning of this tutorial. Now that we've identified where the file exists, we've used that information to download it. We've also checked on the progress of the download, and determined that it is ready to use. At this point, we can set the file name of the new cast member.

Additional Online Resources
Here are some links to related information about this topic:

Please check out the sample files for this tutorial, and read through the commented code. The techniques used in this example can be used to dynamically access many other kinds of media. I hope you find this information useful when building your own projects in Director MX.

About the Author

Joe Sparks is an artist, animator, musician, and game designer. His work has garnered many industry awards, including New Media's Award of Excellence and Macworld Magazine's Game of the Year. Sparks is known for pioneering the multimedia games Spaceship Warlock and Total Distortion, and more recently, for his popular animation series Radiskull & Devil Doll.