Creating Movie Clip Instances Dynamically

You can create a movie clip instance dynamically by using one of the following methods of the Movie Clip class:

  • duplicateMovieClip(): This method duplicates an existing movie clip instance on the stage to create a new instance of that movie clip.

  • attachMovie(): This method creates a new instance of a movie clip directly from the library.

  • createEmptyMovieClip(): This method creates an empty movie clip instancethat is, one that contains no data or graphical content.

You'll use each of these methods in the course of working through the exercises in this lesson.

Using duplicateMovieClip()

Although we introduced the duplicateMovieClip method in Lesson 9, "Automating Scripts with Loops," we didn't cover it in detail. Now you get to learn everything you need to know about this powerful method.

Using the duplicateMovieClip() method, you can direct Flash to duplicate a movie clip instance that's currently on the stage and give it a new instance name. If the movie clip instance is not on the stagethat is, it's in a previous frame or in a frame not yet visitedFlash cannot duplicate it. In addition, the movie clip instance can only be duplicated into the same timeline as the original, and it will exist in the same relative hierarchical position as the original.


To dynamically create a movie clip instance that also allows dynamic timeline insertion, you would use attachMovie() which we'll discuss later in this lesson.

When a movie clip instance is duplicated, the duplicate inherits all of the instance's current physical properties. A duplicated movie clip instance inherits the following properties from the original:

  • Position

  • Scale

  • Alpha

  • Rotation

  • Color

  • Clip events attached to the movie clip instance

A duplicated movie clip doesn't inherit the following:

  • Variables, arrays, objects

  • Name

  • Visibility

  • Current frame



A duplicated movie clip instance starts playing at Frame 1, even if the original from which it was copied was at another frame at the time the duplicate was created.

Following is the syntax for duplicating a movie clip instance:

myClip.duplicateMovieClip(name, depth, object);

This line of ActionScript starts with the instance name (target path) of the movie clip to be duplicated. It then invokes the duplicateMovieClip() method of the Movie Clip class to create a new instance with the value of name at depth. The object parameter is optional. For example:

var name:String = "ball2_mc";

var depth:Number = 100;

ball_mc.duplicateMovieClip(name, depth);

These three lines of ActionScript duplicate the ball_mc movie clip instance, name the new instance ball2_mc, and place it at a depth of 100.

When we talk about depth, we're referring to the stacking order of movie clip instances in a particular timeline. If two movie clip instances overlap in Flash, one must appear to be above the other, with the top instance having a higher depth. Every movie clip instance has a unique depth in relation to other objects on the stage. When a movie clip instance is duplicated, you can assign it a numeric depth of any positive integer. The higher the integer, the higher the depth in that timeline. Although you may not be aware of it, any movie clip instances that you manually place in a particular timeline while authoring a movie are placed at a depth starting from 16384. This means that if a dynamically created instance is placed in a timeline at a depth of 1, it will appear above any manually placed instances.

Each timeline has its own range of depths, from 16384 to 1048575. These depths are relative to the depth of the parent timeline. In other words, instance1 contains child instances at levels on its timeline from 16384 to 1048575. But instance1 is below instance2, so that even the highest-placed child instance in the timeline of instance1 is still lower than the lowest-placed child instance in instance2.



A depth can contain only one movie clip instance at a time. If you duplicate a movie clip instance into a depth that already contains another movie clip instance, you will destroy the movie clip instance that's already there.

Movie clip instances can be placed in a total of 1064960 (16384 to 1048575) depths in a single timeline. Every timeline in a movie has its own set of depths that don't interfere with any other timelines. This means, for example, that you can duplicate instances into a depth of 10 in as many timelines as you like.

The third parameter in the duplicateMovieClip() method, object, is optional but useful. The properties of any object specified in that parameter are used to populate the newly duplicated movie clip instance. If the parameter is left blank, it's ignored. To extend the previous example, look at the following:

var myObject:Object = new Object();

myObject.ballColor = "red"

var name:String = "ball2_mc";

var depth:Number = 100;

ball_mc.duplicateMovieClip(name, depth, myObject);

When ball_mc is duplicated, the duplicate, named ball2_mc, will contain all of the properties of the myObject object. In this case, a variable named ballColor with a value of "red" is created in the new instance.


To copy the variables from the original instance into the duplicate, use the instance name of the original as the initializing object. For example:

ball_mc.duplicateMovieClip(name, depth, ball_mc);

Using attachMovie()

Using attachMovie(), you can actually pull a movie clip out of the library dynamically and attach an instance of it to any timeline currently available on the stagein essence, adding the content of the attached movie clip instance to the content of the movie. The attached movie becomes a child of the timeline to which it's attached. As such, the attached child movie takes on any graphical transformations performed on its parent (size, rotation, transparency, and so on) yet remains separate with respect to data, visibility, current frame, and so on. For more information on parent/child relationships in ActionScript, see Lesson 3, "Understanding Target Paths."


So what are the main differences between the attachMovie() method and the duplicateMovieClip() method? As mentioned earlier, you can use attachMovie() to attach a movie clip instance from the library to any timeline currently in the scene. Because this method attaches clip instances from the library (and the library contains all your movie clips), the attached instance doesn't have to be on stage when you attach it. With duplicateMovieClip(), on the other hand, an instance of the movie clip that you want to duplicate must exist on the stage at the time the method is used. What's more, you must place the duplicate inside the same timeline as the originalyou can't duplicate it to another timeline. In addition, if the instance you're duplicating has any attached clip events (data, enterframe, mouseDown, and so on), the duplicate will automatically inherit those same clip events. Although there are ways to add clip events to an attached movie clip instance, the process is not as straight forward as in the duplication process.


In the simplest terms, attaching movie clip instances allows you to add virtually any timeline to any other timeline. Duplicating movies, in contrast, enables you to make nearly exact replicas of movie clip instances for inclusion in the same timeline as the original.

There are several steps you'll need to follow to use the attachMovie() method in a project, the first of which is to specify, in the library, which movie clips you want to make available for attaching. This is called linkage. Linkage may not seem to be the best term to describe identifying movie clips in the library that can be attached; however, the term also pertains to sharing libraries in which assets in one SWF library are linked, or shared, by another SWF. When specifying movie clips to make available for attaching, or when sharing assets between two SWFs, the movie clips involved must be given identifier names. Macromedia therefore considers as linkage any process that involves giving a movie clip in the library an identifier name.

To add the most common type of linkage to a movie clip, follow these steps:

  1. Open the library.

  2. Right-click the movie clip of interest.

  3. Select Linkage.

  4. Select the Export for ActionScript check box.

  5. Enter the identifier name. (The identifier is how you will refer to this library-based movie clip with ActionScript.)


You can also set the linkage when creating a movie clip in the Convert to Symbol dialog box by clicking the Advanced button.


When setting linkage, there is an option to note: Export in First Frame is checked by default. This option is used to determine when a linked (or attachable) movie clip is downloaded when your project is viewed over the Web. If this box is checked, that movie clip will be downloaded before Frame 1 of your movie so that the clip's content is available before your first opportunity to attach it (that is, Frame 1). If you're using large movie clips (for example, clips that contain many other movie clips or sounds), Flash may appear to hang. Don't worry: it's just preloading the contents of all linked movie clips. If you uncheck the Export in First Frame option, the movie clip will not be preloaded before the first frame as just described. If you choose this option, you must place an instance of that movie clip on the stage at some point before it can be attached, so that Flash knows when to load it. After it's instantiated (seen or placed in your movie) on some frame, you can attach it anywhere. For example, if there's an action on Frame 25 that attaches the movie clip, an instance of that clip must have been placed on Frame 24 or lower for the attachMovie() action to work. Any frames after Frame 24 can attach the instance because it has been loaded into memory.


There's an AS 2.0 Class field in the Convert to Symbol box. If you enter a class name in this field, every instance of the movie clip will inherit the methods and properties of that class, essentially creating a super movie clip. If the specified class file has a run() method, for example, every instance of this class will have that method as well.

Here's the syntax to attach an instance of a movie clip in the library to a timeline:

path.attachMovie(identifier, newName, depth, object)


As with duplicateMovieClip(), the optional object option populates the newly created clip with the properties and variables of an object.

For example:

_root.wall_mc.attachMovie("paint", "paint2_mc", 10)

This script attaches the paint movie clip in the library to the _root.wall_mc movie clip instance. The newly attached movie is given an instance name of paint2_mc and placed on a depth of 10. Because an attached movie becomes a child of the movie clip instance to which it's attached, the newly attached instance will have a target path of _root.wall_mc.paint2_mc.


The easiest way to dynamically assign a clip event to an attached or duplicated movie is to define the assignment immediately after the attachment or duplication action, as the following example shows:

_root.attachMovie("box", "dynamicBox_mc", 1);

dynamicBox_mc.onEnterFrame = function (){

  dynamicBox_mc._rotation += 15;


In this example, an instance of the movie clip named "box" (its identifier name in the library) is dynamically attached to the _root timeline. The attached instance is given a name of dynamicBox_mc. On the next few lines after the attach action, a clip event is assigned to this newly attached instance.

Using createEmptyMovieClip()

Using the createEmptyMovieClip() method, you can dynamically create a new instance of an empty movie clip instance in any timeline. You might do this for the following reasons:

  • With this method, after you've created an empty instance, you can attach other movie clip instances to ituseful for dynamically generating a list of movie clip instances for use as menu choices. After you create this type of "main" movie clip instance, you can move the group around as a whole rather than move each menu item individually.

  • You can create an empty movie clip instance and then dynamically load in music or an image.

  • You can use an empty movie clip instance as a storage area for lines, fills, and gradient fills created using Flash's drawing capabilities.

Here's the syntax for creating an empty movie clip instance in a timeline:

path.createEmptyMovieClip(name, depth);

For example:

_root.createEmptyMovieClip("box_mc", 1);

The first parameter is the instance name that you want to assign to the empty movie clip instance you create; the second parameter is the depth at which you want to place that movie clip instance. If you were to test this action, you wouldn't get a visual result because you're creating an empty movie clip instance. Later in this lesson you'll learn how to use createEmptyMovieClip() to hold drawn lines.

Using attachMovie()

With attachMovie(), you can create a new instance of a movie clip in the library. In this exercise, you'll begin a project that when complete will be a scrolling list of items. You will create the items in the list by attaching movie clip instances dynamically.

  1. Open scrollingList1.fla in the Lesson15/Assets folder.

    There are three layers on the main timeline: Actions, Window, and Background. The Background layer contains the main graphics for the project, the Actions layer contains most of the project's ActionScript, and the Window layer contains a movie clip instance called display_mc.

    Inside the display_mc timeline are four layers: Mask, Fields, Scroll Buttons, and Window Graphics. The Window Graphics layer contains the border and background graphics of the window. The Scroll Buttons layer contains two button instances, down_btn and up_btn, that you will work with in the next exercise. The Fields layer contains an empty movie clip instance called list_mc, which will contain instances that are dynamically created using attachMovie(). These attached instances will appear as items on a list, one on top of the other. When the list_mc movie clip instance is filled with these attached instances, it will become quite long. Thus, list_mc is masked by a rectangular shape in the Mask layer (of its own timeline) so that only the area of list_mc over the window graphics will be visible.


  2. Open the library and locate the movie clip named list info bar. Right-click it (Control-click on a Mac) and select Linkage from the menu that appears. Select Export for ActionScript in the Linkage Properties dialog box that appears and enter infoBar into the Identifier field. Click OK to close the dialog box.

    This movie clip is now available for use with the attachMovie() method.

    One instance of this movie clip will be attached to the list_mc instance for every line of information in the scrolling list (16 lines, 16 attachments). Inside this attached movie clip are two dynamic text field instances, moonName_txt and moonNum_txt, which will be used in the attached instances to display the various names of the moons as well as associated moon numbers.


  3. Select Frame 1 in the Actions layer on the main timeline. Open the Actions panel and enter the following script:

    var list:Array = ["Adrastea", "Amalthea", "Ananke", "Callisto", "Carme", "Elara", "Europa" graphics/ccc.gif, "Ganymede", "Himalia", "Io", "Leda", "Lysithea", "Metis", "Pasiphae", "Sinope", "Thebe"];

    The goal of this exercise is to create a list of items by attaching movie clip instances. To this end, we've created an array of names: the 16 most well-known moons of Jupiter. For each name in this array, an instance of the movie clip in the library to which we previously gave an identifier name will be attached to the list_mc instance.

    Now it's time to begin defining the function that will be used to create the list of movie clip instances.

  4. With Frame 1 still selected, add the following script:

    function buildList () {
      var spacing:Number = 30;

    The buildList() function will ultimately contain all of the ActionScript needed to attach, position, and populate the entire list with movie clip instances. To position the vertical list properly, a variable called spacing is created and given a value of 30, which will be used to set the vertical (y) distance between the center of one attached movie clip instance and the center of the one placed below it.

  5. To attach and position the list items, add the following script to the buildList() function definition, just under the spacing variable:

    for (var i = 0; i < list.length; ++i) {
      var name:String = "infoBar" + i + "_mc";
      var y:Number = i * spacing;
      display_mc.list_mc.attachMovie("infoBar", name, i);
      display_mc.list_mc[name]._y = y;
      display_mc.list_mc[name].moonName_txt.text = list[i];
      display_mc.list_mc[name].moonNum_txt.text = i + 1;

    This part of the function uses a for loop to loop through every element in the list array. For each element in the array, the loop attaches an instance of the infoBar movie clip to the list_mc instance to build the list.

    The first action in the loop creates a variable called name whose value is set using an expression that concatenates the string "infoBar" with the current value of i and "_mc" concatenated on the end. Because the value of i is incremented with each loop, the value of name will be "infoBar0_mc", "infoBar1_mc", "infoBar2_mc", and so on, with each successive iteration of the loop. Further down in the loop, the current value of name is used to assign a name to each successive attached instance of infoBar. Next in the loop, a variable called y is created to store the intended y position of the movie clip instance that's being attached. The value of this variable is based on an expression that multiplies the current value of i by the value of spacing. Because the value of i increases with each iteration, so does the value of y. This results in successive attached instances being placed in a y position below the previous one created.

    The last four actions in the loop attach and populate (with data) the dynamic text fields in each attached instance. An attached instance of the infoBar movie clip is created with an instance name and depth based on the current value of name and i, respectively. This attached instance's y position is then set based on the current value of the variable named y. Because each attached instance contains the same graphical elements as the original, each has two text fields: moonName_txt and moonNum_txt. The last two actions in the loop populate those fields with the appropriate data. Using the current value of i, the text value of moonName_txt in the attached instance is set to the appropriate string value in the list array. Because the value of i is incremented with each loop, the moonName_txt text field in each successively attached instance will display the successive string elements (moon names) in the list array. The moonNum_txt text field in each attached instance is set to a numerical value of i plus 1. This will result in numerical values of 1, 2, 3, and so on appearing in the moonNum_txt text fields of successive attached instances.

    After this loop has been completed, each element in the list array has an attached movie clip instance that's populated with information and appears in an ordered vertical fashion.


  6. To execute the function, add the following line at the end of the current script on Frame 1 (below the function definition):



    After the function has been defined in Frame 1 of the movie, this line of script will execute all the actions we set up in the previous steps.

  7. Choose Control > Test Movie to test what you've created.

    When the movie initializes, your list of items will appear. Remember: because you've used a mask to limit the number of items that can be displayed simultaneously, you'll see only a partial list.

    The list will not scroll yet. That is functionality that you still need to add.

  8. Close the test movie and save your work as scrollingList2.fla.

    You've completed the hardest part of this lesson: you've written ActionScript that dynamically attaches instances of a movie clip from the library to build a list of items. In the next exercise, you'll be working with the same file to make the window scrollable.