Part 3: Creation Process

Step 1: Create a New AS3 Flash Document

Open Flash CS3 (or later) and select File > New... from the application menu. The resulting window will allow you to select a type of document to create. Select "Flash File (ActionScript 3.0)", and click OK. Note that the ActionScript 3 setting is mandatory for the proceeding steps to work.

fig 1.1: Creating a new ActionScript 3.0 document

Save this new Flash document into the provided Lassie resources folder containing the "com" directory. For basic library configuration, the FLA must be contained in the same folder as the Lassie "com" directory, otherwise links to resources within the "com" folder won't work. Be sure to save the document before proceeding.

fig 1.2: The new Flash document should be saved in the same directory as the provided Lassie "com" directory.

Note to Advanced Flash Users:

If you'd like to organize your library FLA's into a neat directory structure, specify a class path for the document that points to Lassie's "com" folder then place the document into any directory structure that you'd like.

Step 2: Set the Document Class.

Click anywhere on the blank document's stage to bring up the document's properties in the Flash Properties Panel (Window > Properties > Properties). Assuming that the document was created as a ActionScript 3 file, there will be property field called "Document class". Enter the following path into the "Document class" field:

com.lassie.pub.lib.MediaLibrary

fig 2-1: Set the document class within the Flash Properties panel.

That path points to a provided script file that will configure the document for use within Lassie. You do not need to alter that script file in any way. Just make sure you reference it properly. The above link will work assuming that your Flash document is saved (emphasis: SAVED) into the Lassie directory containing the "com" folder.

Note to Advanced Flash Users:

You may subclass the provided document class as needed. This could be handy if you'd like to customize the output of library contents by overriding the "contents" getter.

Step 3: Go About Your Business.

Here's where you go about your Flash work as normal. Create library symbols (ie: MovieClips and such), import artwork, design layouts, create animations, etc, just like you always do within Flash. The only trick here is to not set anything up on the main (root) timeline of the document its self. For any and all timeline work, just create a new MovieClip symbol within the library and work within that clip's timeline.

fig 3-1: Document library and document's main (root) timeline.

As your game media develops, it should all exist as just library symbols. If you want to place media onto the document stage while you edit it, that's fine. Just remove it again from the stage when you're finished editing. Ultimately, the document should remain with nothing but a single blank keyframe on its main timeline, just like it was when the document was created. All document assets just exist as symbols within the library.

Step 4: Set Symbol Classes.

In order for library symbols to be extracted and used by Lassie, they must be tagged with a custom identifier defining their "class". You don't need to worry about the technical details of what classes are or how they work, you just need to know the rules and steps of defining them. Once you have given a library symbol a class name (and completed steps 5 and 6), that symbol class will become available within the Lassie engine for use within your game. Non-classified symbols will not appear as options for use within the Shepherd Editor.

Symbol Names versus Class Names

Go into the Flash Library Panel where you'll see a list of all library symbols. The name displayed for each item is its "symbol name", which unfortunately (for the sake of a simple explanation) is meaningless; what we need to define are "class names". This is a slightly confusing point of Flash symbols: what a symbol is called and what ActionScript references it as are two different things. Here's the breakdown:

Symbol name = Flash Library Panel title = meaningless.
Class name = ActionScript identifier = IMPORTANT.

Thankfully, there is no harm in just naming a symbol and its class the same thing, so for the sake of ease and clarity... DO THAT. It makes life a lot easier when you can think of a symbol and its class by the same name, rather than keeping track of what symbol name goes with what class name.

Naming Classes

As we proceed with creating classes, it's important to be aware that we are (in essence) weaving new elements into the fabric of the Flash application structure. As a result, we need to step lightly and make sure we don't accidentally use Flash-specific names that will conflict with the programming of Flash its self (or Lassie for that matter). We also need to make sure that each class name we specify is valid. Don't worry, this sounds a lot scarier than it really is. Follow some simple guidelines and you shouldn't have any problems. Here are the rules:

• Class names are all one word and limited to characters a-z, A-Z, 0-9, and underscore. Also, a class name cannot start with a number as the first character.
• Capitalize class names. Capitalizing the first letter of a class name will automatically isolate it from program properties (which start with lowercase letters). Example: "GoodClassName" verses "badclassname".
• Use mixed case (also known as "camel-case") to separate words. Example: "GoodClassName" versus "Badclassname".
• Be as specific as possible. To use a broad name like "Interface" risks matching a Flash-native class name. So, personalize your names with information specific to your project, like "SkippysRevengeInterface". A good practice would be to start all room-specific objects with the room's name, such as "Room01Bg", and "Room01Table". The more detailed you make the class name, the less likely you will be to encounter a name conflict.
• Class names must be unique. Just like avoiding naming conflicts with Flash, we also need to avoid conflicts between our own class definitions. This is really easy to avoid because Flash will pop an alert message if you try to give two classes the same name.

What to Classify

By giving a library symbol a class, we are enabling ActionScript to extract it from the library and use it within the Lassie engine. However, that does not mean that every single media element in your library needs to be classified for ActionScript. You could drive yourself crazy by specifying that many class definitions! All you need to classify are the primary library symbols that will be used by your game; you DO NOT need to classify all the individual parts and pieces that compose them. Let's look at an example...

The Lassie character sprite is a MovieClip with a frame for each walk cycle, talk animation, rest state, etc. On each one of those frames is a nested MovieClip depicting the specific character animation. So, we'll think of the main character MovieClip (with all the animated states) as the "parent" movie, and each individual character animation placed inside it as "child" MovieClips. In short: the "child" MovieClips are nested inside of the "parent" MovieClip.

When exporting the character MovieClip, the only symbol that would need a class name would be the "parent" clip (or main character movie). All of its child animations will automatically be included with it. The only reason that you would need to classify one of the child movies would be if that individual animation is ever needed by its self (out of context of the parent).

fig 4-1: A "parent" MovieClip timeline with "child" movies placed on it. Exporting the parent will automatically include the children.

So, here's the simple guidelines for choosing media to export:

• [Art Library]: Only classify MovieClips. DO NOT classify bitmaps, graphic symbols, or simple buttons by themselves. If you ever need a non-MovieClip media type placed into your game, just nest it in a new MovieClip and classify that.
• [Art Library]: Only classify MovieClips that are COMPLETE compositions. Do not classify the individual parts and pieces that make up the MovieClip unless the child element is a complete composition that will be used elsewhere by its self.
• [Sound Library]: Only classify Sounds. In fact, sound library documents should never even include any non-sound media.

Setting a Library Symbol's Class Definition

Now that we're up to speed on the basics of how to use classes, you'll be happy to know that the actual process of defining a class is downright simple. Start by going into the Flash library and right-click on a MovieClip symbol to classify. From the context menu that pops up, select "Linkage".

fig 4-1: Opening and configuring the linkage properties window.

A windoid will open with some options. First, check the "Export for ActionScript" option, then make sure the "Export in first frame" option is checked (it should be checked by default). Do NOT check "Enable run-time sharing". There is also a field called "Base class" that should be automatically set to the appropriate value...

The base class for an art library media element should be:

flash.display.MovieClip

The base class for a sound library media element should be:

flash.media.Sound

Again, those values should be set automatically when the linkage panel opens. If they are not, then you're probably exporting a media type that you shouldn't be. Remember, only classify MovieClip symbols within an art library, and only classify Sound symbols within a sound library.

Finally, enter a unique class name in the "Class" field and click "OK". Again, your job will be much easier if you make the class name match the symbol name.

Step 5: Declare the Your Classes.

Home stretch! You've now created media classes that can be used within the Lassie engine; however, Lassie does not know that a class is available within the library without having the class "declared" (ie: stated that the class exists) in a list that the engine can read from. To declare your library's classes, go to the main (root) document timeline where you should (conveniently) find a single blank key frame waiting. If there's more on the main timeline than a single blank keyframe, then go back and review step-3.

Select that single blank keyframe on the main timeline and open the Flash Actions panel (Window > Actions). Within that frame's Actions panel you'll need to add all classes that you've created in your library, formatted as follows:

addClass( SampleLibImage );
addClass( Room01Bg );
addClass( Room01Table );

Of course, the above example's class names should be customized to the names of the classes in your document. List your class declarations one-per line in the actions panel, including every class that you've created within your document. Whenever you add a new class to your library, add its declaration to the main timeline's actions panel. If you ever rename or remove a class, also rename and remove its declaration accordingly. Also, each class should only be declared once (otherwise you could create a naming conflict that results in an error).

Note to Advanced Flash Users:

If you choose to package your library classes, then you'll need to declare your classes by their full DOM path, such as:

addClass( com.package.SampleClass );

Step 6: Publish.

The last step is simply to publish your FLA document (File > Publish). This will compile the FLA into a SWF movie that the Lassie engine can load and extract assets from.

In the perfect world, publishing your library SWF would work every time without error. However, Flash's compiling operation does a check of your document's configuration and will throw errors if it finds any problems (such as: class naming conflicts, missing references, etc). You'll know you've encountered an error if the Flash Output Window pops open with a short error message while publishing. If you encounter a compiler error, don't panic. See the later section in this tutorial that covers common errors and troubleshooting. You'll need to address the error and republish the movie before the library is ready for use within Lassie.

Once you have a compiled and error-free SWF of your media library, login to the media manager section of you Lassie Shepherd development site to upload your media library. Use the upload form to specify the scope and media type of your library (local / global, art / sound). Once you have successfully uploaded your library, the media will be available for use within the Shepherd Editor.