.AS File Format – Packages and the classpath

Packages as dotted names

• A class in a package is declared with its full name: class com.example.ui.Button3D.
• Each part before the last is a folder, so the file is com/example/ui/Button3D.as below a classpath folder.
• The usual convention starts with a reversed domain name, such as com.example; Flash’s own classes use mx, and from Flash 8 the player’s new classes use flash.
• When the movie runs, the class is stored as _global.com.example.ui.Button3D: each package part becomes a plain object. Folder names must therefore be valid identifiers, and a package part cannot have the same name as a class beside it.

import

import com.example.ui.Button3D;   // one class
import flash.filters.*;            // every class in a package

var b:Button3D;                     // instead of com.example.ui.Button3D
var glow:GlowFilter = new GlowFilter(0xFFFFFF, 1, 8, 8);

• import only lets the short name be used; the full name always works without it. It is not #include: it reads no file by itself.
• In a class file, imports come before the class declaration and apply to the whole file.
• In an FLA script, an import applies only to the script it is in: an import on frame 1 does not carry to frame 2 or to a button’s script.
• The wildcard form imports every class in that one package, not in packages below it.
• A class that is imported but never used is not compiled into the SWF.
• Classes in no package, and the built-in classes, need no import.

The classpath

Flash keeps two lists of folders:

The compiler searches the document classpath first, then the global classpath, each from the top of its list down, and takes the first file that matches. Each entry is the root of a package tree; folders below an entry are searched only as package folders. A class must be reachable from the FLA’s classpath together with every superclass and interface it uses.

Because $(LocalData)/Classes comes before ., a class in the FLA’s folder cannot replace one of Flash’s own of the same name unless it is on the document classpath or the global entries are reordered. Flash MX 2004 wrote the entry as $(UserConfig)/Classes. In later versions the compiler maps this one entry to several folders, chosen by the Flash Player version being published for.

MTASC takes its classpath on the command line with -cp, and FlashDevelop passes it from the project settings.

Export frame for classes

The document’s ActionScript 2.0 settings also set the frame in which classes are defined, frame 1 by default. All compiled classes are written into the SWF before that frame’s contents, so a later frame can be used to let a preloader appear before the class code has downloaded. Code that uses a class before that frame finds it undefined.

ASO files

To compile faster, Flash keeps each compiled class as an .aso file in an aso folder inside its user class folder, and reuses it while the .as file’s date is not newer. When files are copied between computers or restored from backup, an older date can make Flash use a stale class. The cure is to delete the ASO files, from Flash 8 with Control, Delete ASO Files, or to give the .as file a newer date.

Leaving classes out

A movie that will be loaded into another can leave out classes the host movie already defines. Flash reads a file named after the FLA with _exclude.xml added, in the FLA’s folder, and does not compile the classes it lists:

<excludeAssets>
  <asset name="com.example.ui.Button3D"></asset>
  <asset name="mx.utils.Delegate"></asset>
</excludeAssets>

The classes are still checked when compiling, as if they were intrinsic.