Monday, March 5, 2012

How to use ActionScript 3 to create a new movie clip instance from the library and then add it to the stage

In this tutorial, we'll learn how to use ActionScript 3 to create an instance of a movie clip symbol that's inside the library. This is useful if you want to create any type of functionality where you'll need to generate instances at runtime. For example, you could create a game that generates enemies at random. You could create a movie clip symbol of the game enemy, keep it in the library, and use ActionScript to create instances of the enemy symbol at random intervals.

Let's begin.

Step 1

Let's start by drawing a shape that we will convert into a movie clip symbol.

Select the oval tool and then use it to draw a circle.

Step 2

Select the entire circle, right click on it, and choose Convert to Symbol. When the Convert to Symbol dialog box comes up, don't click OK just yet. Continue reading to step 3.

Step 3

Name it Circle. Choose Movie Clip as the type. And for the registration point, choose the center.

In the advanced settings, check Export for ActionScript and Export in frame 1. This will enable us to access the symbol using ActionScript, so make sure that you check these options.

For the class name, let's name it Circle. This class name is what we will use every time we want to create an instance of our symbol. This is case sensitive. For the base class, it should say flash.display.MovieClip. Don't change this. If you do, then our symbol will lose all the properties and methods available to a MovieClip object.

Then click OK. If you see a message that says "A definition for this class could not be found in the classpath, so one will automatically be generated in the SWF file upon export.", then click OK as well.

Our symbol should now be accessible using ActionScript 3.

Step 4

Delete the instance of the Circle symbol that's on the stage. We'll now use ActionScript to add one instead.

Step 5

Select frame 1 on the timeline, and choose Window > Actions to bring up the Actions panel.

Step 6

Let's create a new instance of the symbol in our library. The class name that we gave the symbol is Circle. The constructor must match the class name that we specified, so we must use new Circle() in order to create a new instance of the movie clip symbol in our library.

When we create a new instance, it should also have an instance name. Let's name this instance circle1. So in the Actions panel, type:

var circle1:Circle = new Circle();

This will create a new instance of the Circle symbol. But if we test the movie, we won't be able to see it on the stage just yet. That's because we have yet to add it to the display stack. So after the first line, add:


This will add the instance to the display stack so that it can be seen. Test the movie, and you should see the circle on the upper left corner of the stage.

Step 7

If you want to move the instance to a new location, you can use the x and y properties to assign new coordinates. For example:

circle1.x = 250;
circle1.y = 300;

This will move the instance to these new coordinates.

Step 8

We can create more instances by repeating step 6. Add two more instances. Let's name them circle2 and circle3. Then don't forget to add them to the display stack, and change their x and y coordinates.

var circle1:Circle = new Circle();
var circle2:Circle = new Circle();
var circle3:Circle = new Circle();


circle1.x = 250;
circle1.y = 300;
circle2.x = 100;
circle2.y = 200;
circle3.x = 400;
circle3.y = 75;

Then test the movie to see all of the new instances.


  1. Thanks, this is nice lesson for beginners like me.

    But what if I want create 150 instances, at random coordinates each, and not manually entering its names, e.g. goblin1_mc, goblin2_mc...

    Is there some way to generate all these in one cycle, where instance name gets its index from cycle variable?

    1. You could use an array and a for loop.

  2. This is a great, clear, helpful tutorial. Do you have any advice on how I might add instances to the stage dynamically? By which I mean, add instances not when the first frame runs but upon some event, such as a button being clicked?

    1. You can just put the code that adds the circles in an event handler. For more on event handlers: AS3 Event Handlers.

    2. Great! This is working for me. My problem now is that I need to combine this with what the commenter above me was asking about. I want to generate a basically endless chain of instances and the only way I can figure out to do it is just to copy and paste the same chunk of code an absurd amount of times...

  3. What if I want to move the circle based on dice result?