Where do I put all this code?

February 19, 2001
by Will Turnage

Dear Multimedia Handyman:

I am, to say the least, a beginner. I read your articles, and the one question I have (and it may be a dumb one), but where do the sample lines of code in your article go in my movie?

Anonymous Beginner

Dear A.B.:

You are not alone in being a little confused about Director's different script types. The type of script you use determines how often your code gets executed as well as what events call handlers in your code. Essentially, there are four different types of scripts: movie scripts, behaviors, cast member scripts, and parent scripts. In the cast view of your movie, you can tell which kind of script you have by viewing its icon.

Movie scripts, behaviors, and parent scripts are their own separate cast members while cast member scripts are combined with other members.

The Four Types Of Scripts

Movie Scripts

The first type of script is a movie script. Movie scripts contain code that can be called from anywhere in a Director movie regardless of what frame you're on or which sprite gets clicked. If you put a mouseDown handler in a movie script, then that code will execute each and every time the mouse button is pressed in your movie regardless of whether you click on a button or the background. The same applies with pressing keys. If you put a keyUp handler in a movie script, then that code will be executed every time you press and release a key. (Note: There is an exception to this rule which is covered in the next section).

Behaviors

The next type of script is a behavior. Behaviors are scripts that are directly attached to either a frame or a sprite. In older versions of Director, these were called frame scripts or sprite scripts, and you might still encounter those terms. All of the code in Director's Library Palette are behaviors that you can use in your movies. Behaviors differ from movie scripts in that their code is limited to the frame or sprite to which they are attached. So, if you have a mouseDown handler in a behavior attached to a sprite, that handler is executed only when you click on that specific sprite.

Cast Member Scripts

The third type of script is a cast member script. Cast member scripts are similar to behaviors in that they execute code specific to a cast member. If you click on a cast member, then it executes the code in its script. However, cast member scripts are different from behaviors in several ways. First, they are not separate cast members like movie scripts and behaviors; instead they are combined with the member they are assigned to. Second, cast member scripts cannot be shared across different cast members. Each cast member can have its own script, but that's all.

Parent Scripts

The final kind of script is a parent script. Parent scripts are used to create child objects which can have either a global or limited scope. These scripts are most often used for more advanced object oriented programming, which is a whole different topic to be covered in another column. For most basic projects, you won't need to use parent scripts.

The Order of Execution

Now that you know about the types of scripts, you should also know about the order in which scripts get executed. This is helpful when deciding what type of script to use with your code.

Think back to the example of clicking the mouse. When you click the mouse in a Director movie, it generates a mouseDown event. This is the order in which Director processes those events:

Behaviors attached to the clicked sprite
Cast member scripts attached to the clicked sprite's member
Behaviors in the current frame's script channel
Movie scripts containing mouseDown handlers

If Director encounters a mouseDown handler in a behavior attached to a sprite, then it executes that code and the mouseDown handler does not get called in cast member scripts, frame scripts, or movie scripts. If you have mouseDown handlers in a cast member script and a behavior attached to a sprite, then the code in the behavior will always take precedence and the code in the cast member script will never be executed.

While you can't control the order that Director executes the different types of scripts, you can control whether or not the event gets stopped. This is done using the lingo term pass. By using pass, you tell Director that instead of stopping the event with the current type of script, that you want it to send the event on to the next type of script. For example, you could have a behavior attached to a sprite with this code.

on mouseDown me

go marker "theEnd"
pass

end

Without the pass command, Director would execute the code and not pass the event to the next type of script in your movie. But by adding the pass statement, Director will keep looking in cast member scripts, frame scripts, and movie scripts for a mouseDown handler. If it finds one, then it will execute that code and stop the event again unless the word pass is in that code too, at which point it will keep looking down the line for more mouseDown handlers.

Determining which type of script to use

Different Director users have their own preferences on how they like to code projects, so the best way to determine where to put code in your project is to think about the order of execution.

Generally, movie scripts are where you put code that is called at the beginning and end of your movies, or where you put custom handlers that are called throughout your program. For instance, last week's column on resizing your projector gave some code in a prepareFrame handler. This code would always go in a movie script.

Behaviors are used when you need to execute code triggered by clicks or by certain frames in your score. Behaviors can be written specifically for a single button on screen, or they can be used on multiple sprites. The key to using behaviors is that they allow you to have strict control over when and where code gets executed.

For instance, say you wanted to count the number of times the user clicks a button. You could create a simple behavior that increments that number and attach that behavior to every sprite in the score that contains a button:

global gCounter

on mouseUp me

gCounter = gCounter + 1

end

This approach works better than using a movie script because the movie script would execute the code every time the mouse is clicked, not just when a button is clicked. Using a behavior is also better than using a cast member script because this way you just have to write one behavior and then attach it to as many sprites as you want. With cast member scripts, you have to copy and paste the code into each individual cast member which can be very time consuming if you have a lot of buttons.

Hopefully, you've gained an understanding of Director's different types of scripts, and where to put code in your project. Have fun coding!

Will Turnage is a multimedia programmer based in New York City. In addition to his weekly role as Director Online's Multimedia Handyman, he is also the Technology Director for Sony Music's Client Side Technologies Group. You can read more about his work at http://will.turnage.com/.