MACROMEDIA DIRECTOR MX 2004-DIRECTOR SCRIPTING Service manual

DIRECTOR
®
MX
2004
Director Scripting Reference

Trademarks
ActiveEdit, ActiveTest, Add Life to the Web, Afterburner, Aftershock, Andromedia, Allaire, Animation PowerPack, Aria, Attain,
Authorware, Authorware Star, Backstage, Blue Sky Software, Blue Sky, Breeze, Bright Tiger, Clustercats, ColdFusion, Contents
Tab Composer, Contribute, Design In Motion, Director, Dream Templates, Dreamweaver, Drumbeat 2000, EDJE, EJIPT,
Extreme 3D, Fireworks, Flash, FlashHelp, Flash Lite, FlashPaper, Flex, Flex Builder, Fontographer, FreeHand, Generator, Help
To Source, HomeSite, Hotspot Studio, HTML Help Studio, JFusion, JRun, Kawa, Know Your Site, Knowledge Objects,
Knowledge Stream, Knowledge Track, LikeMinds, Lingo, Live Effects, MacRecorder Logo and Design, Macromedia,
Macromedia Action!, Macromedia Central, Macromedia Flash, Macromedia M Logo and Design, Macromedia Spectra,
Macromedia xRes Logo and Design, MacroModel, Made with Macromedia, Made with Macromedia Logo and Design, MAGIC
Logo and Design, Mediamaker, Movie Critic, Open Sesame!, RoboDemo, RoboEngine JFusion, RoboHelp, RoboHelp Office,
RoboInfo, RoboInsight, RoboPDF, 1-Step RoboPDF, RoboFlash, RoboLinker, RoboScreenCapture, ReSize, Roundtrip,
Roundtrip HTML, Shockwave, Sitespring, Smart Publishing Wizard, Software Video Camera, SoundEdit, Titlemaker,
UltraDev, Web Design 101, what the web can be, WinHelp, WinHelp 2000, WinHelp BugHunter, WinHelp Find+, WinHelp
Graphics Locator, WinHelp Hyperviewer, WinHelp Inspector, and Xtra are either registered trademarks or trademarks of
Macromedia, Inc. and may be registered in the United States or in other jurisdictions including internationally. Other product
names, logos, designs, titles, words, or phrases mentioned within this publication may be trademarks, service marks, or trade
names of Macromedia, Inc. or other entities and may be registered in certain jurisdictions including internationally.
Third-Party Information
This guide contains links to third-party websites that are not under the control of Macromedia, and Macromedia is not
responsible for the content on any linked site. If you access a third-party website mentioned in this guide, then you do so at your
own risk. Macromedia provides these links only as a convenience, and the inclusion of the link does not imply that Macromedia
endorses or accepts any responsibility for the content on those third-party sites.
Apple Disclaimer
APPLE COMPUTER, INC. MAKES NO WARRANTIES, EITHER EXPRESS OR IMPLIED, REGARDING THE
ENCLOSED COMPUTER SOFTWARE PACKAGE, ITS MERCHANTABILITY OR ITS FITNESS FOR ANY
PARTICULAR PURPOSE. THE EXCLUSION OF IMPLIED WARRANTIES IS NOT PERMITTED BY SOME STATES.
THE ABOVE EXCLUSION MAY NOT APPLY TO YOU. THIS WARRANTY PROVIDES YOU WITH SPECIFIC
LEGAL RIGHTS. THERE MAY BE OTHER RIGHTS THAT YOU MAY HAVE WHICH VARY FROM STATE TO
STATE.
Copyright © 2004 Macromedia, Inc. All rights reserved. This manual may not be copied, photocopied, reproduced,
translated, or converted to any electronic or machine-readable form in whole or in part without prior written approval of
Macromedia, Inc.
Second Edition: September 2004
Macromedia, Inc.
600 Townsend St.
San Francisco, CA 94103

3
CONTENTS
CHAPTER 1: Introduction. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Intended audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
What’s new with Director scripting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
What’s new in this documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Finding information about scripting in Director . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
CHAPTER 2: Director Scripting Essentials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Types of scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Scripting terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Scripting syntax. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Data types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Literal values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Conditional constructs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Events, messages, and handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Linear lists and property lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
JavaScript syntax arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
CHAPTER 3: Writing Scripts in Director . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Choosing between Lingo and JavaScript syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Scripting in dot syntax format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Introducing the Director objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Object model diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Top level functions and properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Introduction to object-oriented programming in Director . . . . . . . . . . . . . . . . . . 54
Object-oriented programming with Lingo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Object-oriented programming with JavaScript syntax . . . . . . . . . . . . . . . . . . . . . . 65
Writing scripts in the Script window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73

4 Contents
CHAPTER 4: Debugging Scripts in Director . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Good scripting habits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Basic debugging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Debugging in the Script window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Debugging in the Message window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Debugging in the Object inspector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Debugging in the Debugger window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Debugging projectors and Shockwave movies . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Advanced debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
CHAPTER 5: Director Core Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
CHAPTER 6: Media Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
CHAPTER 7: Scripting Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
CHAPTER 8: 3D Objects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
CHAPTER 9: Constants. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
CHAPTER 10: Events and Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
CHAPTER 11: Keywords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
CHAPTER 12: Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
CHAPTER 13: Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595
CHAPTER 14: Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617
INDEX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1103

5
CHAPTER 1
Introduction
This reference provides conceptual and how-to information about scripting in Macromedia
Director MX 2004, and also provides reference descriptions and examples for the scripting
application programming interfaces (APIs) that you use to write scripts.
The scripting APIs are the means by which you access the functionality of Director through
script to add interactivity to a movie. By using these APIs, you can create interactive functionality
that is identical to that provided by the prewritten behaviors that are shipped with Director, in
addition to functionality that is more powerful and more varied than that provided by the
prewritten behaviors.
The prewritten behaviors enable you to add basic interactive functionality to a movie, such as
moving the playhead to a frame number or marker, or zooming in when a user clicks a sprite.
They also enable non-interactive functionality such as sprite animation, media loading, and frame
navigation. The scripting APIs enable you to extend and customize these types of functionality.
Intended audience
This reference is intended for you if you want to do any of the following:
•Extend the existing functionality of prewritten behaviors by using script.
•Add functionality to a movie by using script instead of prewritten behaviors.
•Add more powerful, varied, and custom functionality to a movie than that provided by
prewritten behaviors.
This reference is intended to provide all the information, from basic to advanced, you need to add
interactivity to your movies by using script. Therefore, you do not need to have any prior
scripting experience to write effective scripts in Director.
Regardless of your experience level with Director, Lingo, or JavaScript syntax, take a few moments
to browse Chapter 2, “Director Scripting Essentials,” on page 9 and Chapter 3, “Writing Scripts
in Director,” on page 49 before you begin writing scripts. Like any product, Director has its own
unique set of scripting conventions, types of data, and so on. You will need to be comfortable
with these unique characteristics of Director before you can write effective scripts.

6 Chapter 1: Introduction
What’s new with Director scripting
If you have written scripts in previous versions of Director, you should note some new and
important changes about scripting in this latest release.
Dot syntax scripting format
In previous releases of Director, you could write Lingo scripts by using two types of syntax:
verbose syntax or dot syntax. Verbose syntax was very similar to English, and was relatively easy
for new programmers to learn. However, verbose syntax scripts quickly became long and complex,
and were difficult to debug.
Now that the scripting model of Director is compatible with both Lingo and JavaScript syntax,
scripts should be written only in dot syntax. Dot syntax will be familiar to many programmers,
since it is the syntax used in most object-oriented languages such as Java or C++, and in many
web-based scripting languages such as Microsoft JScript or JavaScript.
To support backwards compatibility, scripts written by using verbose syntax in previous versions
of Director will still run. However, starting with Director MX 2004, dot syntax is the
recommended syntax to use, and is the only syntax that will be supported and documented in
the future.
For more information on using dot syntax to write scripts, see “Scripting in dot syntax format”
on page 50.
JavaScript syntax compatibility
Director is now compatible with JavaScript syntax. This means that in addition to being able to
author and debug scripts by using Lingo, which is the long-time scripting language of Director,
you can choose to author and debug scripts by using JavaScript syntax. The implementation of
JavaScript in Director is referred to as JavaScript syntax throughout this reference.
The support of JavaScript syntax in Director helps create a scripting environment that is familiar
not only to JavaScript developers but also to developers experienced with Macromedia Flash
ActionScript, Macromedia Flash Communication Server, Macromedia Dreamweaver,
Macromedia Authorware, and a number of other environments.
The implementation of JavaScript syntax in Director is JavaScript 1.5, which means that it is fully
compliant with the ECMAScript Language Specification ECMA-262, 3rd Edition. Almost all of
the features and functionality in JavaScript 1.5 are now available in Director.
For more information on choosing Lingo or JavaScript syntax, see “Choosing between Lingo and
JavaScript syntax” on page 49.
Note: This reference is intended to only discuss the features and functionality of the JavaScript 1.5
implementation that are essential to writing JavaScript syntax scripts in Director. It is not intended to
provide a complete reference for JavaScript 1.5. For more detailed information on JavaScript 1.5 than
is provided in this reference, see one of the many third-party resources on the subject.
New ways to access the scripting APIs
In this release of Director, the scripting APIs have been grouped into objects, and are accessed
through these objects. These objects contain the functionality required to add interactivity to
your movies and are accessible to both Lingo and JavaScript syntax within Director, projectors,
and Macromedia Shockwave Player.

Finding information about scripting in Director 7
Although the way you access the scripting APIs in this release may vary from previous releases,
you still have access to the same APIs that you did before, in addition to some brand new ones.
The only difference is that you access them by using the new objects.
For more information on the objects and their corresponding scripting APIs, see “Introducing the
Director objects” on page 51.
What’s new in this documentation
If you learned how to script in previous versions of Director, you should know about some
changes in the scripting documentation for this release. The Director Scripting Reference takes the
place of the Lingo Dictionary that was shipped with previous versions of Director. This reference is
organized differently than the Lingo Dictionary.
In the Lingo Dictionary, information about the scripting model was organized by feature.
For example, if you wanted to learn how to work with sprites in script, you looked up that
information in one of the sections under the Sprites heading, such as Dragging Sprites, Sprite
Dimensions, and so on. In addition, all of the scripting APIs were listed in a single alphabetical
list, which meant that all functions, properties, events, and so on were mixed together
alphabetically.
In the Director Scripting Reference, information about the scripting model is organized by object.
This organization closely reflects the organization of the actual scripting objects that you use in
your scripts. For example, if you want to find out how to work with sprites in script, you should
look for the Sprite section in the chapter, Director Core Objects.
The scripting APIs are still listed in alphabetical order, but they are categorized by API type. For
example, all methods are listed alphabetically under the Methods heading, all properties are listed
alphabetically under the Properties heading, and so on.
Finding information about scripting in Director
With its new organization, the Director Scripting Reference contains the following topics:
Director Scripting Essentials Provides information about the basic scripting concepts and
components you will use when scripting in Director.
Writing Scripts in Director Provides information about the Director scripting environment in
addition to advanced scripting concepts and techniques.
Debugging Scripts in Director Provides information about how to find problems in your
scripts when they are not performing as expected.
Director Core Objects Provides a list of the objects and APIs that you use to access the core
functionality and features in Director, such as the Director player engine, movie windows, sprites,
sounds, and so on.
Media Types Provides a list of the media types and APIs that you use to access the functionality
of the various media types in Director, such as RealMedia, DVD, Animated GIF, and so on, that
are added to movies as cast members.
Scripting Objects Provides a list of the scripting objects, also known as Xtra extensions, and
APIs that you use to extend core Director functionality. Xtra extensions provide capabilities such
as importing filters and connecting to the Internet.
3D Objects Provides a list of the objects you use to add 3D functionality to a movie.

8 Chapter 1: Introduction
Constants Provides a list of the constants that are available in Director.
Events and Messages Provides a list of the events that are available in Director.
Keywords Provides a list of the keywords that are available in Director.
Methods Provides a list of the methods that are available in Director.
Operators Provides a list of the operators that are available in Director.
Properties Provides a list of the properties that are available in Director.

9
CHAPTER 2
Director Scripting Essentials
If you are new to scripting in Macromedia Director MX 2004, you may want to take some time
to learn the basic scripting concepts that are essential to understanding how to script in Director
before you begin. Some of these essentials include definitions of important terms, syntax rules,
available data types, and information about the basic elements of scripting in Director—for
example, variables, arrays, operators, and so on.
Types of scripts
A Director movie can contain four types of scripts: behaviors, movie scripts, parent scripts, and
scripts attached to cast members. Behaviors, movie scripts, and parent scripts all appear as
independent cast members in the Cast window. A script attached to a cast member is associated
with that cast member in the Cast window and does not appear independently.
•Behaviors are scripts that are attached to sprites or frames in the Score, and are referred to as
sprite behaviors or frame behaviors. The Cast window thumbnail for each behavior contains a
behavior icon in the lower right corner.
When used in the Director Scripting Reference, the term behavior refers to any script that you
attach to a sprite or a frame. This differs from the behaviors that come in the Director Library
Palette. For more information on these behaviors, which are built into Director, see the Using
Director topics in the Director Help Panel.
All behaviors that have been added to a cast library appear in the Behavior inspector’s Behavior
pop-up menu. Other types of scripts do not appear there.
You can attach the same behavior to more than one location in the Score. When you edit a
behavior, the edited version is applied everywhere the behavior is attached in the Score.
•Movie scripts contain handlers that are available globally, or on a movie level. Event handlers in
a movie script can be called from other scripts in the movie as the movie plays.
A movie script icon appears in the lower right corner of the movie script’s Cast window
thumbnail.
Movie scripts are available to the entire movie, regardless of which frame the movie is in or
which sprites the user is interacting with. When a movie plays in a window or as a linked
movie, a movie script is available only to its own movie.

10 Chapter 2: Director Scripting Essentials
•Parent scripts are special scripts that contain Lingo that is used to create child objects. You can
use parent scripts to generate script objects that behave and respond similarly yet can still
operate independently of each other. A parent script icon appears in the lower right corner of
the Cast window thumbnail.
For information on using parent scripts and child objects, see “Object-oriented programming
with Lingo” on page 55.
JavaScript syntax does not use parent scripts or child objects; it uses regular JavaScript syntax-
style object-oriented programming techniques. For information on object-oriented
programming in JavaScript syntax, see “Object-oriented programming with JavaScript syntax”
on page 65
•Scripts attached to cast members are attached directly to a cast member, independent of the
Score. Whenever the cast member is assigned to a sprite, the cast member’s script is available.
Unlike behaviors, movie scripts, and parent scripts, cast member scripts do not appear in the
Cast window. However, if Show Cast Member Script Icons is selected in the Cast Window
Preferences dialog box, cast members that have a script attached display a small script icon in
the lower left corner of their thumbnails in the Cast window.
Scripting terminology
Both Lingo and JavaScript syntax use some terms that are specific to each language, in addition to
some terms that are shared between each language.
Important scripting terms are listed here in alphabetical order. These terms are used throughout
the Director Scripting Reference, so it will help to understand these terms before moving forward.
•Constants are elements whose values do not change. For example, in Lingo, constants such as
TAB, EMPTY, and RETURN always have the same values, and cannot be modified. In JavaScript
syntax, constants such as Math.PI and Number.MAX_VALUE always have the same values, and
cannot be modified. You can also create your own custom constants in JavaScript syntax by
using the keyword const.
For more information on constants, see “Constants” on page 20.
•Events are actions that occur while a movie is playing. Events occur when a movie stops, a
sprite starts, the playhead enters a frame, the user types at the keyboard, and so on. All events
in Director are predefined, and always have the same meaning.
For more information on events, see “Events” on page 33.
•Expressions are any part of a statement that produces a value. For example, 2 + 2 is
an expression.
•Functions refer to either top-level functions or specific types of JavaScript syntax code.
A top-level function instructs a movie to do something while the movie is playing or returns a
value, but it is not called from any specific object. For example, you would call the top-level
list() function by using the syntax list(). Like a function, a method also instructs a movie
to do something while the movie is playing or returns a value, but it is always called from
an object.
A function is used in JavaScript syntax to represent an event handler, a custom object, a custom
method, and so on. The use of JavaScript functions in these cases is described in the applicable
topics later in this reference.

Scripting terminology 11
•Handlers, or event handlers, are sets of statements within a script that run in response to a
specific event and subsequent message. When an event occurs, Director generates and sends
a corresponding message to scripts, and a corresponding handler runs in response to the
message. The names of handlers are always the same as the events and messages they
respond to.
Note: Although in JavaScript syntax an event is actually handled by a function, the term handler is
used generically throughout this reference to refer to both Lingo handlers and JavaScript syntax
functions that handle events.
For more information on handlers, see “Handlers” on page 35.
•Keywords are reserved words that have a special meaning. For example, in Lingo, the keyword
end indicates the end of a handler. In JavaScript syntax, the keyword var indicates that the
term following it is a variable.
•Lists (Lingo) or Arrays (JavaScript syntax) are ordered sets of values used to track and update
an array of data, such as a series of names or the values assigned to a set of variables. A simple
example is a list of numbers such as [1, 4, 2].
For more information on using lists in both Lingo and JavaScript syntax, see “Linear lists and
property lists” on page 38.
For more information on using JavaScript syntax arrays, see “JavaScript syntax arrays”
on page 45.
•Messages are notices that Director sends to scripts when specific events occur in a movie. For
example, when the playhead enters a specific frame, the enterFrame event occurs and
Directors sends an enterFrame message. If a script contains an enterFrame handler, the
statements within that handler will run, because the handler received the enterFrame message.
If no scripts contain a handler for a message, the message is ignored in script.
For more information on messages, see “Messages” on page 34
•Methods are terms that either instruct a movie to do something while the movie is playing or
return a value, and are called from an object. For example, you would call the insertFrame()
method from the Movie object, using the syntax _movie.insertFrame(). Although similar in
functionality to top-level functions, methods are always called from an object, and top-level
functions are not.
•Operators are terms that calculate a new value from one or more values. For example, the
addition (+) operator adds two or more values together to produce a new value.
For more information on operators, see “Operators” on page 25.
•Parameters are placeholders that let you pass values to scripts. Parameters only apply to
methods and event handlers, and not to properties. They are required by some methods and
optional for others.
For example, the Movie object’s go() method sends the playhead to specific frame, and
optionally specifies the name of the movie that frame is in. To perform this task, the go()
method requires at least one parameter, and allows for a second parameter. The first required
parameter specifies what frame to send the playhead to, and the second optional parameter
specifies what movie the frame is in. Because the first parameter is required, a script error will
result if it is not present when the go() method is called. Because the second parameter is
optional, the method will perform its task even if the parameter is not present.

12 Chapter 2: Director Scripting Essentials
•Properties are attributes that define an object. For example, a sprite in a movie has specific
attributes, such as how wide it is, how tall it is, its background color, and so on. To access the
values of these three specific attributes, you would use the Sprite object’s width, height, and
backColor properties.
For more information on assigning properties to variables, see “Storing and updating values in
variables” on page 21.
•Statements are valid instructions that Director can execute. All scripts are made up of sets of
statements. The following Lingo is a single complete statement.
_movie.go("Author")
For more information on writing script statements, see “Scripting in dot syntax format”
on page 50
•Variables are elements used to store and update values. Variables must start with a letter, an
underscore (_), or the dollar sign ($). Subsequent characters in a variable name can also be
digits (0-9). To assign values to variables or change the values of many properties, you use the
equals (=) operator.
For more information on using variables, see “Variables” on page 21.
Scripting syntax
The following are general syntax rules that apply to Lingo and JavaScript syntax.
•Comment markers vary between Lingo and JavaScript syntax.
All Lingo comments are preceded by double hyphens (--). Each line of a comment that covers
multiple lines must be preceded by double hyphens.
-- This is a single-line Lingo comment
-- This is a
-- multiple-line Lingo comment
JavaScript syntax comments on a single line are preceded by a double-slash (//). Comments
that cover multiple lines are preceded with a /* and followed by a */.
// This is a single-line JavaScript syntax comment
/* This is a
multiple-line JavaScript syntax comment */
You can place a comment on its own line or after any statement. Any text following the
comment markers on the same line are ignored.
Comments can consist of anything you want, such as notes about a particular script or handler
or notes about a statement whose purpose might not be obvious. Comments make it easier for
you or someone else to understand a procedure after you’ve been away from it for a while.
Adding large numbers of comments does not increase the size of your movie file when it is
saved as a compressed DCR or DXR file. Comments are removed from the file during the
compression process.
Comment markers can also be used to ignore sections of code you want to deactivate for
testing or debugging purposes. By adding comment markers rather than removing the code,
you can temporarily turn it into comments. Select the code you want to turn on or off, and
then use the Comment or Uncomment buttons in the Script window to quickly add or remove
comment markers.

Scripting syntax 13
•Parentheses are required after all method and function names. For example, when calling the
Sound object’s beep() method, you must include the parentheses after the word beep.
Otherwise, a script error will occur.
// JavaScript syntax
_sound.beep(); // this statement will work properly
_sound.beep; // this statement will result in a script error
When you call a method, function, or handler from within another method, function, or
handler, you must include parentheses in the calling statement. In the following example, the
modifySprite() method contains a call to a spriteClicked handler. The call to the
spriteClicked handler must include parentheses; otherwise, a script error occurs.
// JavaScript syntax
function modifySprite() {
spriteClicked(); // this call to the handler will work properly
spriteClicked; // this call to the handler results in a script error
}
function spriteClicked() {
// handler code here
}
You can also use parentheses to override the order of precedence in math operations, or to
make your statements easier to read. For example, the first math expression below yields a
result of 13, while the second expression yields a result of 5:
5 * 3 - 2 -- yields 13
5 * (3 - 2) -- yields 5
•Event handler syntax varies between Lingo and JavaScript syntax. In Lingo, handlers use the
syntax on handlerName. In JavaScript syntax, handlers are implemented as functions, and use
the syntax function handlerName(). For example, the following statements comprise a
handler that plays a beep when the mouse button is clicked:
-- Lingo syntax
on mouseDown
_sound.beep()
end
// JavaScript syntax
function mouseDown() {
_sound.beep();
}
•Event handler parameter syntax can vary between Lingo and JavaScript syntax. Both Lingo and
JavaScript syntax support enclosing parameters passed to a handler within parentheses. If more
than one parameter is passed, each parameter is separated by a comma. In Lingo, you can also
pass parameters that are not enclosed by parentheses. For example, the following addThem
handler receives the two parameters aand b.
-- Lingo syntax
on addThem a, b -- without parentheses
c = a + b
end
on addThem(a, b) -- with parentheses
c = a + b
end
// JavaScript syntax
function addThem(a, b) {
c = a + b;
}

14 Chapter 2: Director Scripting Essentials
•The const keyword can be used in JavaScript syntax to specify a constant whose value does not
change. Lingo has its own predefined set of constants (TAB, EMPTY, and so on); therefore, the
keyword const does not apply to Lingo.
For example, the following statement specifies a constant named intAuthors and sets its value
to 12. This value will always be 12, and cannot be changed through script.
// JavaScript syntax
const intAuthors = 12;
•The var keyword in JavaScript syntax can be placed in front of a term to specify that the term
is a variable. The following statement creates a variable named startValue.
// JavaScript syntax
var startValue = 0;
Note: Although using var in JavaScript syntax is optional, it is recommended that you always
declare local JavaScript syntax variables, or those inside a function, using var. For more
information on using variables, see “Variables” on page 21.
•The line continuation symbol (\) in Lingo indicates that a long line of sample code has been
broken into two or more lines. Lines of Lingo that are broken in this way are not separate lines
of code. For example, the following code would still run.
-- Lingo syntax
tTexture = member("3D").model("box") \
.shader.texture
JavaScript syntax does not include a line continuation symbol. To break multiple lines of
JavaScript syntax code, add a carriage return at the end of a line, and then continue the code on
the following line.
•Semicolons can be used to specify the end of a statement of JavaScript syntax code. Semicolons
do not apply to Lingo.
Using a semicolon is optional. If used, it is placed at the end of a complete statement. For
example, both of the following statements create a variable named startValue.
// JavaScript syntax
var startValue = 0
var startValue = 0;
A semicolon does not necessarily specify the end of a line of JavaScript syntax code, and
multiple statements can be placed on one line. However, placing separate statements on
separate lines is recommended in order to improve readability. For example, the following
three statements occupy only one line of code and function properly, but it is difficult to
read the code.
// JavaScript syntax
_movie.go("Author"); var startValue = 0; _sound.beep();
•Character spaces within expressions and statements are ignored in both Lingo and JavaScript
syntax. In strings of characters surrounded by quotation marks, spaces are treated as characters.
If you want spaces in a string, you must insert them explicitly. For example, the first statement
below ignores the spaces between the list items, and the second statement includes the spaces.
-- Lingo syntax
myList1 = ["1", "2", "3"] -- yields ["1", "2", "3"]
myList2 = [" 1 ", " 2 ", " 3 "] -- yields [" 1 ", " 2 ", " 3 "]

Data types 15
•Case-sensitivity can vary between Lingo and JavaScript syntax.
Lingo is not case-sensitive in any circumstance—you can use uppercase and lowercase letters
however you want. For example, the following four statements are equivalent:
-- Lingo syntax
member("Cat").hilite = true
member("cat").hiLite = True
MEMBER("CAT").HILITE = TRUE
Member("Cat").Hilite = true
Although Lingo is not case-sensitive, it’s a good habit to choose a case convention and use it
consistently throughout your scripts. This makes it is easier to identify names of handlers,
variables, cast members, and so on.
JavaScript syntax is case-sensitive when referring to objects, the top level properties or methods
that refer to objects, or when referring to user-defined variables. For example, the top level
sprite() method returns a reference to a specific Sprite object, and is implemented in
Director with all lowercase letters. The first statement below refers to the name of the first
sprite in a movie, while the second and third statements result in a script error.
// JavaScript syntax
sprite(1).name // This statement functions normally
Sprite(1).name // This statement results in a script error
SPRITE(1).name // This statement results in a script error
Literal strings are always case-sensitive in both Lingo and JavaScript syntax.
For more information on using strings, see “Strings” on page 18.
Data types
A data type is a set of data with values that have similar, predefined characteristics. Every variable
and property value in Director is of a specific data type, and values returned by methods are of a
specific data type.
For example, consider the following two statements. In the first statement, variable intX is
assigned a whole number value of 14, which is an integer. So, the data type of variable intX is
integer. In the second statement, variable stringX is assigned a sequence of character values,
which is a string. So, the data type of variable stringX is string.
-- Lingo syntax
intX = 14
stringX = "News Headlines"
// JavaScript syntax
var intX = 14;
var stringX = "News Headlines";
The values that are returned by methods or functions are also of an inherent data type. For
example, the Player object’s windowPresent() method returns a value that specifies whether a
window is present. The returned value is TRUE (1) or FALSE (0).

16 Chapter 2: Director Scripting Essentials
Some data types are shared between Lingo and JavaScript syntax, and some data types are specific
to one language or another. The set of data types that Director supports is fixed and cannot be
modified, meaning that new data types cannot be added and existing data types cannot be
removed. Director supports the following data types.
Data type Description
# (symbol) A self-contained unit that can be used to represent a condition or flag. For example,
#list or #word.
Array (JavaScript syntax only) Although not literally a data type, an Array object can be
used to work with linear lists of values. The functionality of an Array object is similar
to that of the List data type in Lingo.
Boolean A value that is TRUE (1) or FALSE (0). In Lingo, all TRUE or FALSE values are simple
integer constants, 1 for TRUE, 0 for FALSE. In JavaScript syntax, all true or false
values are by default the actual Boolean true or false values, but are converted to
simple integer constants automatically when required in Director.
In Lingo, TRUE and FALSE can be either lowercase or uppercase. In JavaScript
syntax, true and false must always be lowercase.
Color Represents an object’s color.
Constant A piece of data whose value does not change.
Date Although not literally a data type, in JavaScript syntax a Date object can be used to
work with dates. In Lingo, use the date() method to create a Date object and work
with dates.
Float (Lingo only) A floating-point number. For example, 2.345 or 45.43.
Function (JavaScript syntax only) Although not literally a data type, a Function object can be
used to specify a string of code to run.
Integer (Lingo only) A whole number. For example, 5 or 298.
List A linear or property list made up of values or property names and values,
respectively.
Math (JavaScript syntax only) Although not literally a data type, a Math object can be
used to perform mathematical functions.
null (JavaScript syntax only) Denotes a variable whose value behaves as 0 in numeric
contexts and as FALSE in Boolean contexts.
Number (JavaScript syntax only) Although not literally a data type, a Number object can be
used to represent numerical constants, such as a maximum value, not-a-number
(NaN), and infinity.
Object Although not literally a data type, an Object object can be used to create a custom
named container that contains data and methods that act on that data.
Point A point on the Stage that has both a horizontal and vertical coordinate.
Rect A rectangle on the Stage.
RegExp (JavaScript only) A regular expression pattern that is used to match character
combinations in strings.
String A contiguous sequence of keyboard symbols or character values. For example,
"Director" or "$5.00".

Data types 17
Note: Many of the data types and objects that are specific to JavaScript syntax contain their own set
of methods and properties that can be used to further manipulate those types. While the Director
Scripting Reference may refer to some of these methods and properties, it does not include complete
reference information about them. For more detailed information on these data types and objects,
and their methods and properties, see one of the many third-party resources on the subject.
The built-in properties in Director, such as the Cast object’s name property, can only be assigned
values that are the same data type as that of the property’s inherent data type. For example, the
Cast object’s name property’s inherent data type is a string, so the value must be a string such as
News Headlines. If you try to assign a value of a different data type to this property, such as the
integer 20, a script error occurs.
If you create your own custom properties, their values can be of any data type, regardless of the
data type of the initial value.
Both Lingo and JavaScript syntax are dynamically typed. This means that you do not have to
specify the data type of a variable when you declare it, and data types are automatically converted
as needed while a script runs.
For example, the following JavaScript syntax initially sets the variable myMovie to an integer, and
later in the script it is set to a string. When the script runs, the date type of myMovie is converted
automatically.
-- Lingo syntax
myMovie = 15 -- myMovie is initially set to an integer
...
myMovie = "Animations" -- myMovie is later set to a string
// JavaScript syntax
var myMovie = 15; // myMovie is initially set to an integer
...
myMovie = "Animations"; // myMovie is later set to a string
undefined (JavaScript syntax only) Denotes a variable that does not have a value.
Vector A point in 3D space.
VOID (Lingo only) Denotes an empty value.
Data type Description

18 Chapter 2: Director Scripting Essentials
Literal values
A literal value is any part of a statement or expression that is to be used exactly as it is, rather than
as a variable or a script element. Literal values that you encounter in script are character strings,
integers, decimal numbers, cast member names and numbers, frame and movie names and
numbers, symbols, and constants.
Each type of literal value has its own rules.
Strings
Strings are words or groups of characters that script treats as regular words instead of as variables.
Strings must be enclosed in double quotation marks. For example, you might use strings to give
messages to the user of your movie or to name cast members. In the following statement, Hello
and Greeting are both strings. Hello is the literal text being put into the text cast member;
Greeting is the name of the cast member.
-- Lingo syntax
member("Greeting").text = "Hello"
Similarly, if you test a string, double quotation marks must surround each string, as in the
following example:
-- Lingo syntax
if "Hello Mr. Jones" contains "Hello" then soundHandler
Both Lingo and JavaScript syntax treat spaces at the beginning or end of a string as a literal part of
the string. The following expression includes a space after the word to:
// JavaScript syntax
trace("My thoughts amount to ");
Although Lingo does not distinguish between uppercase and lowercase when referring to cast
members, variables, and so on, literal strings are case-sensitive. For example, the following two
statements place different text into the specified cast member, because Hello and HELLO are
literal strings.
-- Lingo syntax
member("Greeting").text = "Hello"
member("Greeting").text = "HELLO"
In Lingo, the string() function can convert a numerical value into a string. In JavaScript syntax,
the toString() method can convert a numerical value into a string.
Note: Attempting to use the toString() method in JavaScript syntax on a null or undefined value
results in a script error. This is in contrast with Lingo, in which the string() function works on all
values, including those that are VOID.
Numbers
In Lingo, there are two types of numbers: integers and decimals.
An integer is a whole number, without any fractions or decimal places, in the range of
-2,147,483,648 and +2,147,483,647. Enter integers without using commas. Use a minus (-) sign
for negative numbers.

Literal values 19
A decimal number, also called a floating-point number, or float, is any number that includes a
decimal point. In Lingo, the floatPrecision property controls the number of decimal places
used to display these numbers. Director always uses the complete number, up to 15 significant
digits, in calculations; Director rounds any number with more than 15 significant digits in
calculations.
JavaScript syntax does not distinguish between integers and floating-point numbers, and merely
uses numbers. For example, the following statements illustrate that the number 1 is an integer in
Lingo and a number in JavaScript syntax, and that the decimal number 1.05 is a float in Lingo
and a number in JavaScript syntax:
-- Lingo syntax
put(ilk(1)) -- #integer
put(ilk(1.05)) -- #float
// JavaScript syntax
trace(typeof(1)) // number
trace(typeof(1.05)) // number
In Lingo, you can convert a decimal to an integer by using the integer() function. You can
also convert an integer to a decimal by performing a mathematical operation on the integer, for
example, by multiplying an integer by a decimal. In JavaScript syntax, you can convert a string or
a decimal number to a whole number by using the parseInt() function. As opposed to Lingo’s
integer() function, parseInt() rounds down. For example, the following statement rounds
off the decimal number 3.9 and converts it to the integer 4 (Lingo) and the number 3
(JavaScript syntax).
-- Lingo syntax
theNumber = integer(3.9) -- results in a value of 4
// JavaScript syntax
var theNumber = parseInt(3.9); // results in a value of 3
In Lingo, the value() function can convert a string into a numerical value.
You can also use exponential notation with decimal numbers: for example, -1.1234e-100 or
123.4e+9.
In Lingo, you can convert an integer or string to a decimal number by using the float()
function. In JavaScript syntax, you can convert a string to a decimal number by using the
parseFloat() function. For example, the following statement stores the value 3.0000 (Lingo)
and 3 (JavaScript syntax) in the variable theNumber.
-- Lingo syntax
theNumber = float(3) -- results in a value of 3.0000
// JavaScript syntax
var theNumber = parseFloat(3) // results in a value of 3

20 Chapter 2: Director Scripting Essentials
Constants
A constant is a named value whose content never changes.
In Lingo, the predefined terms TRUE, FALSE, VOID, and EMPTY are constants because their values
are always the same. The predefined terms BACKSPACE, ENTER, QUOTE, RETURN, SPACE, and TAB
are constants that refer to keyboard characters. For example, to test whether the last key pressed
was the Space bar, use the following statement:
-- Lingo syntax
if _key.keyPressed() = SPACE then beep()
In JavaScript syntax, you can access predefined constants using some of the data types that are
unique to JavaScript syntax. For example, the Number object contains constants such as
Number.MAX_VALUE and Number.NaN, the Math object contains constants such as Math.PI and
Math.E, and so on.
Note: This reference does not provide in-depth information about the predefined constants in
JavaScript syntax. For more information on these constants, see one of the many third-party
resources on the subject.
In JavaScript syntax, you can also define your own custom constants by using the const keyword.
For example, the following statement creates a constant named items, and assigns it a value of 20.
This value cannot be changed after it has been created.
// JavaScript syntax
const items = 20;
For more information on constants, see Chapter 9, “Constants,” on page 151.
Symbols
A symbol is a string or other value in Lingo that begins with the pound (#) sign.
Symbols are user-defined constants. Comparisons using symbols can usually be performed very
quickly, providing more efficient code.
For example, the first statement below runs more quickly than the second statement:
-- Lingo syntax
userLevel = #novice
userLevel = "novice"
Symbols cannot contain spaces or punctuation.
In both Lingo and JavaScript syntax, convert a string to a symbol by using the symbol() method.
-- Lingo syntax
x = symbol("novice") -- results in #novice
// JavaScript syntax
var x = symbol("novice"); // results in #novice
Convert a symbol back to a string by using the string() function (Lingo) or the toString()
method (JavaScript syntax).
-- Lingo syntax
x = string(#novice) -- results in "novice"
// JavaScript syntax
var x = symbol("novice").toString(); // results in "novice"