Written by: Evgueni Strok
Difficulty Level: Beginner
Requirements: Flash 5 or above
Download FLA

The attachmovie method places a movieclip (from the current SWF's library) on the stage in real time. attachmovie is often used in games and navigation where multiple copies of the same movieclip are required. For instance, in a space-invaders style game where multiple copies of the same enemy clip are required, attachmovie can be used to attach a variable number of enemies and setProperty can be used to place them about the stage in formation.
someMCInstanceName.attachmovie(idName, newname, depth);



someMCInstanceName is the path to a timeline into which we wish to place a copy of the library clip. In our example we have a Movie Clip (MC_main) with an instance name "main".


idName is the linkage name of the movie in the library to attach. The linkage name is the name entered in the Identifier field in the Symbol Linkage Properties dialog box.

In Flash 5

1) Open the Library window
2) Right click a movieclip in the library and choose a Linkage...
3) In Symbol Linkage Properties window choose a "Export this symbol" and type your idName

The process is the same for Flash MX however Flash MX allows you to enable or disable (via the checkbox) loading the movieclip before the first frame.

How linkage works

Linkage allows you to attach and use movieclips from the library at run time, but because Flash doesn't know when you're going to ask for a copy, it loads linked items before anything else to ensure they are available as soon as the movie starts playing. This can cause troubles when using a preloader as all linked content in the library will be loaded even before your preloader. In Flash MX you can disable this function by unchecking the 'Export in First Frame' option, however to ensure Flash loads the movieclip, you must physically place it somewhere in the SWF. Flash will load the clip when it reaches the frame you place it on, so it will only be available from that frame onwards. In Flash 5 this option is not supported. One good way to preload SWFs which make extensive use of linkage is to use an external 'wrapper' SWF, whose sole purpose is to load in your SWF. If you want to do that, try this external SWF preloader script by Jesse.

newname A unique instance name for the movie clip being attached.

depth An integer specifying the depth level where the movie is placed. Note that depth and levels in Flash are two separate concepts, so don't get them confused.

Let's attach a movieclip from a button:

button1

on (release) {
 main.attachmovie("att1", "newname1", 1);
}

button2

on (release) {
 main.attachmovie("att2", "newname2", 1);
}

button3

on (release) {
 main.attachmovie("att3", "newname3", 1);
}

Note that in all the examples above we are simply replacing the previously attached movieclip because we are using the same depth each time. Each attached instance must have a unique depth if you don't want it to replace any other. This is often achieved using a counter variable which you increment by one each time you attach a clip.

Once an attached clip is on the stage you can use the removeMovieClip method to remove it, and all other MovieClip Object methods to manipulate it as you please.