Runtime Shared Library Tutorial (Flash CS4)

Runtime shared libraries enable ActionScript programmers to separate the design and development aspects of their project. The designer can work on the graphics in the shared library, while the programmer codes the functionality elsewhere. This can be useful for small projects, but it is essential for larger projects that can become unwieldy if your assets are not properly organized. This tutorial will walk you through setting up a runtime shared library and loading it into a simple project.

This is the general procedure for using a runtime shared library:

1. Create the library swf file containing the shared assets
2. Create the project swf file that uses the shared assets
3. Allow the library and project to communicate via ActionScript

During runtime, the shared asset library will be dynamically loaded into the project swf. Then, all of the assets defined in the shared library will be available to the project swf. Voila! Your graphics are separated from your ActionScript code. Now, we’ll cover each of these steps in detail. Or, you can jump to the source.

Step 1: Creating the shared assets

Our runtime shared library will be called ‘Assets.swf’. Create a new FLA called ‘Assets.fla’ in the same directory as ‘Assets.fla’. We need to create a graphical asset to share with the project swf. The asset that we will be sharing is called ‘SharingIsCaring’. To create this asset:

1. Create a new MovieClip by pressing CTRL+F8.
2. For the name of the clip, input ‘SharingIsCaring’.
3. You also need to export this MovieClip for it to be available to the project swf, so click the checkbox for ‘Export for ActionScript’ an leave the default ‘SharingIsCaring’ for the Class name.
4. Create any graphic you like for the MovieClip. I drew a blue circle with the words ‘Sharing Is Caring’ in the middle of it.
5. Press CTRL+ENTER to publish ‘Assets.swf’, and that’s it for the shared library.

Not so bad, huh? If you were working with a graphic designer, you would create dummy MovieClips for all of the graphics that you’re using in your project. Then, give ‘Assets.fla’ to your graphic designer, so he/she can create the real graphics. While he/she is doing so, you are free to code the functionality for the project. When you are ready to update the graphics, simply swap your copy of ‘Assets.swf’ with the designer’s version. All of your graphics will magically update, and you won’t have to change a thing about your code. But remember, your designer’s copy of ‘Assets.fla’ must export the same MovieClips as your copy. So, if you add another dummy asset, make sure to tell your designer to add the same asset to his/her shared library.

Step 2: Creating the project that uses the shared assets

Now it’s time to build the project that will import the graphics from the shared library that we just made. We’ll call our project ‘Project.fla’. To set up the project, create this file, then follow these steps:

1. Associate the project fla with a class. In ‘Project.fla’, set the DocumentClass to ‘Project’. Create a file called ‘Project.as’ in the same folder. Put this code in it:
   package {
   
    import flash.display.*;
    import flash.events.*;
    import flash.net.*;
    import flash.system.ApplicationDomain;
    import flash.system.LoaderContext;
    import flash.utils.getDefinitionByName;
   
    public class Project extends Sprite{
       
        public function Project(){
           
        }

    }
}

   This simply creates the foundation of the class and imports the necessary packages.

2. Load the shared asset library into the project. Add this to the constructor function in ‘Project.as’
   public function Project(){
            // this context is necessary to find the shared assets
            var context:LoaderContext = new LoaderContext(false,
                                        ApplicationDomain.currentDomain);
           
            // load in the asset swf
            var loader:Loader = new Loader();
            var req:URLRequest = new URLRequest("Assets.swf");
            loader.contentLoaderInfo.addEventListener(Event.COMPLETE,
                                                      onAssetsLoaded);
            try{
                loader.load(req, context);
            }catch(e:Error){
                trace("Asset load error: " + e);
            }
        }

   The asset library is loaded the same way we would load any other dynamic graphic: via the Loader class. If you’ve used the Loader class before, this should be familiar to you. What may not be familiar, however, is the use of LoaderContext and ApplicationDomain. These classes define the way a dynamically loaded swf interacts with its parent swf. In this case, using ApplicationDomain.currentDomain will make all of the asset library’s classes available to the ‘currentDomain’, which is ‘Project.as’.

3. We still need to define what happens when the library is done loading. This is accomplished with the function ‘onAssetsLoaded’, which we told the Loader to call when loading is complete in the last step. When the library is loaded, we’ll get an instance of the shared MovieClip and add it to the stage. Add this to ‘Project.as’:
   private function onAssetsLoaded(_event:Event):void{
            // the name of the shared asset
            var assetName:String = "SharingIsCaring";
           
            // get the MovieClip class of the asset
            var assetClass:Class = getDefinitionByName(assetName) as Class
           
            // create an instance of the shared asset
            var sharedAsset:DisplayObject = new assetClass();
           
            // position the asset
            sharedAsset.x = 100;
            sharedAsset.y = 100;
           
            // add asset to the stage
            addChild(sharedAsset);
        }

   First, we define the name of the asset that we are looking for as ‘SharingIsCaring’. Then, we need to find a reference to the class ‘SharingIsCaring’, which is exported in ‘Assets.swf’. We cannot do this directly, since hardcoding something like

   var myAsset:SharingIsCaring = new SharingIsCaring();

   will output a compiler error, because the class ‘SharingIsCaring’ is not available to ‘Project.as’ at compile time. It is defined in ‘Assets.swf’ and will only be available at runtime, after the library is loaded into the project (hence the name ‘Runtime Shared Library’). This is why we must use the wonderfully useful AS3 function ‘getDefinitionByName();’ to find the class of the graphical asset. Once we have the class, we create an instance of the shared MovieClip. This instance can be treated like any other MovieClip. We just position it and add it to the stage.

You’ve just loaded a runtime shared library into a simple Flash project. If this were the real world, you could start coding some functionality into ‘Project.as’ while your designer worked on ‘Assets.fla’ at the same time.

Let’s take it one step further. What if you don’t know what assets are defined in your runtime shared library. For example, the library may define a group of objects that is to be displayed dynamically by the project. To accomplish this, you will need a way to communicate what assets the library defines. We’ll do this by passing an array containing the names of the classes that ‘Assets.swf’ exports.

Step 3: Communicating via ActionScript (the lazy friendly way)

First, we’ll take a look at a very simple method of communicating between the asset library and the project. The MovieClips that the asset library exports are not the only thing available to the project at runtime. All of the variables and functions defined in ‘Assets.fla’ are also available to ‘Project.swf’ This means we can tell the project which classes are available in the asset library by creating a variable in the root of ‘Assets.fla’.

Open up ‘Assets.fla’, create a new layer, label it ‘actions’, then put the following into the actions panel (F9):

Now we need to access this variable from the project. Change ‘onAssetsLoaded();’ to the following.

Instead of explicitly coding the asset name (‘SharingIsCaring’), we use the ‘availableGraphics’ variable that we defined on the root timeline of ‘Assets.fla’. This may seem like a trivial difference, but it makes it much easier to add to new assets, which we will do now.

Create another MovieClip in ‘Assets.fla’ called ‘AnotherAsset’. Use the same method as described for the ‘SharingIsCaring’ MovieClip. To inform ‘Project.as’ that this new asset is available, all we have to do is add it to the ‘availableGraphics’ array in ‘Assets.fla’:

Export ‘Assets.fla’. Now open up ‘Project.swf’. Wow! Another asset! And we didn’t even have to compile the project again!

An aside: I call this the ‘lazy’ way to communicate between ‘Assets.swf’ and ‘Project.swf’ because it isn’t the technical, object-oriented way of doing this. If you don’t really care about object-oriented programming, you can skip this paragraph. In order to be ‘proper’, you would need to create an interface that explicitly defines the communication (e.g., a hardcoded ‘getAssets():Array’ method instead of an assumed ‘availableGraphics’ property). You would then make ‘Assets.fla’ implement this interface, which would force you to create an ‘Assets.as’ document class for the shared library. After all of this, ‘Project.as’ can use the interface to know, with absolute certainty, that the shared asset library has a function called ‘getAssets();’. If you want to use this communication method, you’ll have to take a look at the source code. Honestly, it doesn’t make a difference to me if ‘Project.as’ knows if the asset library has this method. I’m perfectly content with making my assumed variable a convention for the project, because, after all, isn’t an interface just an explicitly defined convention? But, I digress…You don’t really need to know any of this to make good use of a runtime shared library, so don’t worry about it.

Well, that should get you started with runtime shared asset libraries. Keep in mind that these libraries can define more than just graphical assets for a project: they can define ActionScript classes as well. They can also be useful for themes. By swapping a different asset library for your current one, you are effectively applying a new ’skin’ to your project. If you have any interesting applications of runtime shared libraries, feel free to post them in a comment below.

I’ll leave you with the source code for the tutorial, and best wishes towards implementing your own runtime shared library.