Endsley - Basic Director Tips 2: Scripting

Fred Endsley

Basic Director Scripting and Lingo

Types of Scripts:

There are 4 basic kinds of scripts: frame scripts, sprite/button scripts, movie scripts, and castmember scripts. All scripts, complete or incomplete, are listed in the script box of the upper-left of the score window. Before a movie is finished, any incomplete or unused scripts should be deleted.

All scripts are cast members. They can be created in script windows by defining 'variables', or by using 'handlers' (eg. "on exitFrame", "on mouseUp", "on startMovie") to initiate an 'event' which is determined and defined by following lingo statements.

The interior elements of scripts between the handler ("on exitFrame", etc.) and the "end", are indented to indicate their correct structure and function. To check proper indentation, use the Tab key. Scripts which do not indent properly are probably not written correctly and may not function as intended. Scripts must be completed with the unindented term "end", and finally authorized/entered by hitting 'return' (or enter) and/or closing the script window.

They can be changed or added to, like any text-editing function, as long as the indentation and protocol for "end" is correct. Each script can contain numerous lingo statements which define several separate events, or define and extend the same event.

In the beginning, scripts and their lingo statements should be kept as simple and clear as possible to avoid confusion and bugs. Scripts can be viewed as the movie plays by opening the Message window (comm-m) and checking the Trace box. Bugs can then be corrected directly from the Message window. Tracing the scripts as the movie plays also recompiles all the scripts so that they execute more smoothly.

Many bugs (eg. misspelling, undefined frames, handlers, and other variables) will be detected with an alert when you close the script window after entering and "ending" the script. However, many bugs can also go undetected until someone stumbles over them. You should allow sufficient time to de-bug your application, using a variety of people (esp. children) to play through the entire application, before committing it to publication.

Movie scripts - entered by selecting an empty castmember slot before opening the script window. When you do open the script window it should say "Movie Script". Existing movie scripts are then accessible through the script window.
Movie scripts are often for identifying variables/functions that are to be 'global', that is: active and TRUE or FALSE throughout the movie or related sequence of movies until defined otherwise. Movie scripts generally start with the 'handler': "on startMovie" or "on stopMovie", followed by lingo definition of the variables, and "end".
Frame scripts - attached to individual frames in the Score frame channel to define the occurrence of events, variable changes, etc. during or immediately following the current frame(s), such as tempo/clock or sound events. Frame scripts generally start with the handlers: "on exitFrame", or "on enterFrame", followed by the lingo definition of the event(s), and "end".
Sprite scripts - attached to individual or a selected range of sprites in one or more score channels. They are used to define variables and events that can be applied to a sprite or enabled through interaction with the sprite (eg. buttons, progression, or branching). Sprite scripts generally start with handlers like: "on mouseUp", "on mouseDown", "on keyUp", "on keyDown", "if rollOver", etc., followed by the lingo definition(s),and "end".
Cast member scripts - can be attached to individual or a range of cast members in the cast window so that every time the particular cast members appear in the score, they are affected or controlled by the defining lingo of their scripts. These scripts don't necessarily need initiating handlers, but should still end with "end". Cast member scripts are good to define consistent events related to the cast member such as button event definitions like: "pause", "go to...", or "continue".

Entering Scripts:

Scripts and their Lingo statements can be entered manually through the score script window by double-clicking the particular frame of the script channel or the particular sprite cell to which they will be attached. Or the script window can be opened by selecting a script channel frame or sprite cell(s), and then clicking on the long gray rectangle near the top of the score window. To open multiple script windows, Option-click the arrows in the script window.

Scripts that have been already written or used are available to be selected and entered in open script windows from the score window script pull-down menu. You can also choose 'clear' from that pull-down menu to cancel a script function, or 'new' to write a new script for a selected frame or cell that already has a script attached to it. Scripts can carry over to all cast members of the same name or number that are entered into the score unless you select 'new' from the pull-down script menu to write a new script for a particular selected frame or cell.

Basic Lingo Statements:

The elements of many lingo statements are contained in the alphabetical/categorical lingo menu which is available when a script window is open. These 'pieces' of code can be entered and combined directly from the lingo menu to the script window, or used as a basis for manually writing scripts in the script window.

I use a macro program like Quick Keys to record and enter frequently used scripts or lingo statements; this is especially helpful for creating long, complex scripts in the late night hours when typos and memory lapses are more frequent. Using the Copy-Paste extension is also very useful because it allows up to 10 different scripts to be stored on the clipboard.

Another good way for keeping track of often used or important scripts is by keeping a Simple Text page open to copy scripts onto and out of. This 'script log' can then be saved for later use or 'cannibalization' for other hybrid scripts. There are also tons of scripts available online.

There are thousands of lingo statements that are predefined by Director or can be written and defined by the individual users. These are a bunch of simple and frequently used ones (italic words indicate variables to be defined by users).

Basic Script Elements and Examples:

Note: Indentations may not be exact.

on exitFrame standard handler to initiate event to occur immediately after leaving current frame; "on exitFrame" can be changed to "on enterFrame" to initiate event to occur immediately when playback head arrives at selected frame.

go to moves playback head to a specified location in the current score or the score of another movie. Related movies should be grouped in the same folder and alphabetically named relative to play-order. Frame locations in a score can be specified by frame #, or by setting frame 'markers' at the top of the score.
Named frame markers can be moved to different frames at any time. Be careful when deleting frames (comm-[) that you don't also delete necessary frame markers. When frame marker names or movies are entered in "go to" scripts, the literal name should be enclosed in quotation marks. Scripts are not case sensitive, though capitals are often used for readability.
eg.
go to frame 26,
go to frame "loop2"
go to frame "door" of movie "aMenu1"

the Frame	refers to the current frame
go to the Frame	loops playback head in current frame
the Frame - 1	refers to the previous frame (the Frame - 2 is two frames previous)
the Frame + 1	refers to the next frame (etc.)
go next	moves playback head to next marker in the score
go previous	moves playback head to previous marker in the score
go loop	loops playback head between current frame and previous marker to the left in the score
pause	stops movie in referenced frame (no longer used in Director 6)
continue	moves playback head beyond 'pause frame' (no longer used in Director 6)

delay	delays the forward progress of the playback head for the specified number of "ticks", but allows continued playing of sound.
the timeoutLength	a 'timeout' occurs when the elapsed time between mouse or keyboard actions exceeds the specified or default amount of 'ticks'. Ticks are a measurement of computer time based on 60 ticks per second. It can be expressed as a total number of ticks, or as number of seconds x 60 ticks. Thus the lingo expressions 3600, or 60 * 60 both equal 60 seconds or 1 minute. The default setting at the start of each movie is 3 minutes or 10800 or 180 * 60.
set the timeoutLength to (# of ticks)	useful for setting the amount of time a movie will remain in a paused or looped state before automatically moving to another specified location.
when timeout then	defines what will occur when the movie clock reaches the specified 'timeoutLength'
set the timeoutLapsed to	resets the movie clock to 0; timeoutLength setting or default still controls the limit of movie clock until timeout occurs.
when timeout then nothing	redefines a specified timeout event so that 'nothing' will happen; this is 'true' until the next 'when timeout then' definition.

Frame Script Example:

on enterFrame
set the timeoutLapsed to 0
set the timeoutLength to1800
when timeout then go to frame "exit"
pause
end
combined with Sprite Script attached to button "Menu":
on mouseUp
go to frame "menu" of movie "Fork"
end
combined with Sprite Script attached to button "Continue":
on mouseUp
continue
end
This set of lingo statements written in three separate scripts, but contained within the same frame, specifies that upon entering the referenced frame, the movie clock is reset to 0, the timeoutLength is set to run out at 30 seconds, if (when) the timeoutLength is reached the movie goes to the frame specified as "exit", and the movie is paused during the current frame.
The movie clock is still 'ticking' away during a pause.
If the user mouse-clicks the button "Main Menu" during the pause and before the timeoutLength runs out, the movie will go to the frame "menu" of the movie "Fork".
If the user mouse-clicks the button "continue" during the pause and before the timeoutLength runs out, the movie will move out of the paused state and proceed to the next frame.
These related scripts are useful for allowing a viewer to stop, perhaps to read text at his/her own speed (within the timeout limit), and to choose to continue or return to a menu. If the viewer looses interest, the movie will exit automatically after the specified time, in this case, 30 seconds.

unLoadMember (castmember # or "name")

clears specified preloaded cast member(s) from memory so that movie can play better.

eg.

unLoadMember 16	clears castmember #16 from memory
unLoadMember 4, 22	clears all castmembers from #4 through #22 from memory

random

defines numeric limit/range of property to which random is applied

eg.

on exitFrame
set the forecolor of sprite 18 = random (256)
go to the frame
end

Upon leaving the current frame, this script randomly resets the foreground color of sprite 18 to any of the 256 colors in the system palette. The playback head is told to loop continuously, entering and exiting only within the 'current' frame, so that the forecolor of sprite 18 is continually being reset to a random choice from the system palette.

the text of cast (# or name)

Determines the 'string' that is the text contained in an editable text castmember. Useful for displaying messages, or recording or responding to what a user types on the keyboard.

eg.

on keyDown
if the key = return then set the text of member 23 = "Thanks!"
end

if the last key entered was 'return' (perhaps following a text data entry requested by text castmember 23 to "Please enter your name and phone number followed by the 'return' key"), then the text of castmember 23 is replaced by the text "Thanks!". This change is true until the movie is closed and opened again, or the text is reset by lingo.

eg. Sprite Script attached to 'check box' button:

on mouseUp
set the text of cast "no text/correct" = "That's Right !!!"
end if the user mouse-clicks this button (in correct response to a question), the specified text cast member (which up til then contained no text) now contains and displays "That's Right !!!"

on enterFrame
repeat while mouseDown = TRUE
beep
end repeat
end causes computer to 'beep' as long as mouse button is depressed.

play (frame # or "name", movie "name", etc.) plays specified frame or movie; then if play command was issued by frame script, playback head returns to the next frame automatically. If play command was issued by a sprite script, playback head returns to the same frame.

play done when a "playing" movie reaches a frame with the "play done" script, playback head returns to the frame (or frame immediately after - see above) where the "play" script was originally issued.

if the key = "r" and the commandDown then restart restarts computer when user presses command-r

if the key = "q" and the commandDown then quit quits application when user presses command-q

if the key = "d" and the optionDown then shutDown shuts down computer if user presses option-d

Sound Scripts

sound fadeIn (channel #), (# of ticks) fade in sound in specified sound channel over course of specified time (expressed in ticks)
eg.

on exitFrame
sound fadeIn 1, 180
sound fadeOut 2, 240
end sound in channel 1 fades in during next 3 seconds (180 ticks), while sound in channel 2 fades out during next 4 seconds (240 ticks)

sound stop 1 stops the sound playing in channel 1.

set the soundLevel to 5 resets the sound volume of computer to 5 (out of 1-7)

set the volume of sound 2 to 203 sets the sound volume of sound in channel 2 to 203 (out of possible 255 - 0 is mute)

if soundBusy (2) then go to the frame if sound is playing in channel 2 then the playback head loops in the current frame allowing sound to finish before proceeding. Sound will not play during a paused frame or when playback head is told to go to another location or movie.

if soundBusy 1 then sound stop if sound is playing in sound channel 1 during selected frame, then sound is terminated.

sound playFile 4, "Rub-a-dub" plays sound file (AIFF or WAVE) "Rub-a-dub", which is external to Director movie, in "channel 4". Normally there are only 2 sound channels available to Director, but this command allows for sounds to be played from up to 8 channels, though playback/RAM can be compromised.

Cursor Scripts

cursor 0
cursor -1
cursor 1
cursor 2
cursor 3
cursor 4
cursor 200 resets cursor to specified default cursor (usually arrrow)
arrow
I-beam
crosshair
crossbar
watch
invisible/inactive
eg.

on enterframe
if the cursor of sprite 8 = 0
then set cursor to [7]
else if the cursor of sprite 4 = 0
then set the cursor to [9]
else cursor 3
end if
end If the default cursor is over the sprite of channel 8 during or after the frame then the cursor becomes a custom cursor of castmember 7 which must be a 1-bit, B/W 16 pixel x 16 pixel pict. If the cursor is over the sprite of channel 4 during or after the frame, then the cursor becomes a custom version of castmember 9. Otherwise, the cursor is changed to the crossbar (3).
Note: when writing 'if . . . then' statements, it often works better to hit 'return' before the 'then' part of the statement. Both indentation and function are often more correct.

Rollover and Case Scripts

on enterFrame
if rollover (6) then play frame "eruption"
else
if rollover (7) then play frame "bubbles"
else
if rollover (8) then play frame "diggity-do"
else
if rollover (9) then play frame "turkey trot"
else
if rollover (10) then go to movie "Fly"
else nothing
end if
end If
end if
end If
end This script assumes that all affected sprites have first been puppetted.

If the cursor rolls over any sprites in channels 6-9, the movie goes to and plays the specified frame, then returns to the frame where the rollover occurred. If the cursor rolls over sprite in channel 10, the playback head goes to movie "Fly" and proceeds from there.

Notice the balanced, nested structure of "ifs", "elses", and "end ifs". In this form of script, all the "if" statements should be balanced out with "end if"s.

Or

on enterFrame
case the rollOver of
6: play frame "eruption"
7: play frame "bubbles"
8: play frame "diggity-do"
9: play frame "turkey trot"
10: go to movie "Fly"
otherwise nothing
end case
end This can be expressed more compactly using
the "case" statement to do exactly the same thing.
Note how "otherwise" replaces "else" in this version.

Puppet Scripts

puppetSprite 12, TRUE makes the sprite inchannel 12 a puppet so that it can be controlled separately by lingo. This remains True until

puppetSprite 12, False removes puppet condition from sprite 12

puppetSound 1, "Bark.aif" plays sound file "Bark.aif" in sound channel 1; overides any other sound currently playing in channel 1.

puppetSound 0 stops all puppetSounds; returns control back to score sound channels.

puppetPalette "Metallic" resets movie's palette to "Metallic" until command

puppetPalette 0 returns palette to prepuppet status

on enterFrame
puppetSprite 5, TRUE
if rollover (5) then set the foreColor of sprite 5 to 253
else set the foreColor of Sprite 5 to 255
end

on mouseDown
puppetSprite 5, FALSE
end

on mouseUp
go to frame "bugout"
end

If the cursor 'rolls over' puppetSprite 5, the foreColor of puppetSprite 5 is lightened 2 shades, causing it to appear to "glow"

On the mouseDown of the button this script is written for, puppetSprite 5 is "de-puppetized"

After the sprite has been de-puppetized, the movie can move to another frame ("bugout") without carrying along the complications of a puppetted sprite. If possible, all sprites should be de-puppetized before moving to a new part of the score.

on exitFrame
repeat with channel = 17 to 21
puppetSprite channel, TRUE
end repeat

set the foreColor of sprite 17 = random (256)

set the locH of sprite 19 = random (640)
set the locV of sprite 19 = random (480)

set the memberNum of sprite 18 to 5

set the ink of sprite 20 to 36

set the visible of sprite 21 to FALSE

puppetSound "Space Disrupter"

when timeout then go to movie "epilogue"

updateStage

go to the frame
end

the variable "channel" is set to contain the values of sprites "17-21". The sprites in channels 17-21 are declared "puppets", so they can be controlled by lingo.
The foreground colors of sprite 17 are reset randomly as any of the 256 8-bit system palette colors.
The horizontal and vertical locations are reset randomly within the full boundaries of the 640 x 480 screen.
The castmember of sprite 18 is switched for castmember 5.
The ink of sprite 20 is set to 'background transparent'.
Sprite 21 is made invisible.
The sound of sound cast member "Space Disrupter" is played (puppet sounds are normally played from sound channel 1.
When a default or previously set timeoutLength is reached, the playback head goes to the movie "epilogue" which negates all the puppet settings.
The stage is redrawn to 'update' the random sprite changes and play the puppetSound each time the playback head loops within the frame.
The playback head is set to 'loop' continually, exiting & entering "the frame".

on enterFrame
puppetSprite 8, True
set the moveableSprite of sprite 8 to True
if sprite 8 intersects sprite 15
then go to frame "X"
else nothing
end

Upon entering the frame, the sprite of channel 8 is declared a puppet. That puppetSprite (8) is then defined as 'moveable' by the user (dragging it with the mouse). If that same sprite 8 is then moved across the screen so that it intersects the boundary of the sprite in channel 15, then the playback head moves to the frame "X".

on exitFrame
puppetSprite 6, True
set the moveableSprite of sprite 6 to True
set the constraint of sprite 6 to 14
if sprite 6 intersects sprite 9
then set the constraint of sprite 6 to 0
else nothing
go to the frame
end

Upon exiting the frame, the sprite of channel 6 is declared a puppet. That puppetSprite (6) is then defined as 'moveable', but constrained within the boundaries if sprite 14.

If that sprite 6 intersects sprite 9, then sprite 6 is no longer constrained within the boundries of sprite 14. This can all occur while the frame is looping.

on mouseDown
puppetSprite 16, True
set the locH of Sprite 16 to the mouseH
set the locV of Sprite 16 to the mouseV
beep 2
update stage
end

When the mouse button is depressed (perhaps while over a particular shape or area on stage, the sprite of channel 16 is declared to be a puppet, then reset to the same screen coordinates/location as the current mouse cursor's position.

The computer beeps 2 times. The stage is updated.

on mouseDown
puppetSprite 7, True
repeat while the mouseDown
repeat with n = 14 to 15
set the memberNum of sprite 7 = n
set the locH of sprite 7 = the mouseH
set the locV of sprite 7 = the mouseV
updateStage
end repeat
end repeat
end

This script would probably be used during a single-frame loop.

While the mouse button is depressed puppetSprite 7 is 'attached' to the cursor, and its castmember is continuously switched between two other cast members (14 and 15) which seem to "buzz" as they follow the cursor around.

The stage is updated continuously to reflect the changes.

on mouseUp
puppetSprite 1, True
set n = the memberNum of Sprite 1
set n = n+1
if n <= 26 then set the memberNum of Sprite 1 to n
updateStage
end

Another script to be used during a single-frame loop.

This enables sequential exchange of cast members (as for a slide show) through cast member 26.

play (frame # or "name", movie "name", etc.)	plays specified frame or movie; then if play command was issued by frame script, playback head returns to the next frame automatically. If play command was issued by a sprite script, playback head returns to the same frame.
play done	when a "playing" movie reaches a frame with the "play done" script, playback head returns to the frame (or frame immediately after - see above) where the "play" script was originally issued.

if the key = "r" and the commandDown then restart	restarts computer when user presses command-r
if the key = "q" and the commandDown then quit	quits application when user presses command-q
if the key = "d" and the optionDown then shutDown	shuts down computer if user presses option-d

on exitFrame sound fadeIn 1, 180 sound fadeOut 2, 240 end	sound in channel 1 fades in during next 3 seconds (180 ticks), while sound in channel 2 fades out during next 4 seconds (240 ticks)
sound stop 1	stops the sound playing in channel 1.
set the soundLevel to 5	resets the sound volume of computer to 5 (out of 1-7)
set the volume of sound 2 to 203	sets the sound volume of sound in channel 2 to 203 (out of possible 255 - 0 is mute)
if soundBusy (2) then go to the frame	if sound is playing in channel 2 then the playback head loops in the current frame allowing sound to finish before proceeding. Sound will not play during a paused frame or when playback head is told to go to another location or movie.
if soundBusy 1 then sound stop	if sound is playing in sound channel 1 during selected frame, then sound is terminated.
sound playFile 4, "Rub-a-dub"	plays sound file (AIFF or WAVE) "Rub-a-dub", which is external to Director movie, in "channel 4". Normally there are only 2 sound channels available to Director, but this command allows for sounds to be played from up to 8 channels, though playback/RAM can be compromised.

puppetSprite 12, TRUE	makes the sprite inchannel 12 a puppet so that it can be controlled separately by lingo. This remains True until
puppetSprite 12, False	removes puppet condition from sprite 12
puppetSound 1, "Bark.aif"	plays sound file "Bark.aif" in sound channel 1; overides any other sound currently playing in channel 1.
puppetSound 0	stops all puppetSounds; returns control back to score sound channels.
puppetPalette "Metallic"	resets movie's palette to "Metallic" until command
puppetPalette 0	returns palette to prepuppet status