Reference to the Scripting language for SWF

Defines one action. Actions will be included in a DO ACTION or a BUTTON object.

[ expr [ { ',' expr } ] ]

The action expressions depend on the action. Note that an action is determined by the name given right after the action keyword. Actions with the same name can be included multiple times in the same list. Some actions don't accept any expression (such as the actions START and STOP).

Example:

ACTION "GOTO" { "ShowFunkyButtons" };

In order to adhere to a better script standard, Macromedia decided to add some new arthmetic and comparison instructions. These new instructions won't change the type of the parameters involved unless otherwise necessary (if you compare an integer with a string, then (a) if the string can be transformed in a value, compare two values otherwise (b) the integer is first transformed in a string and a string comparison is done). The older instructions still work as before. These always try to cast strings in integer or floating point values in before arthmetic and comparison operations. The result may not always be the one expected ("1" + "2" is "12" with the new operator and "3" with the old one). To help distinguish among both sets of instructions, this scripting language uses CAST at the end of such instructions (see the ADD CAST for instance). When the CAST is present the old instruction is used.

In the following list, you will find action names with spaces. Any of these names can be written with no separator, a space ( ), an underscore (_), a period (.) or a dash (-). For instance, all of the following are valid for a branch always action: BRANCHALWAYS, BRANCH ALWAYS, BRANCH_ALWAYS, BRANCH.ALWAYS, BRANCH-ALWAYS.

A few actions are defined as objects because they can include other actions. These objects are listed here:

Object	Action
CATCH	CATCH
FINALLY	FINALLY
FUNCTION	FUNCTION
LABEL	LABEL
TRY	TRY
WITH	WITH

Finally, instructions can be included in lists and sub-lists as required.

[ LABEL | GOTO ':' ] expr

[ LABEL | GOTO ':' ] expr

{ [ STRING ':' ] expr }

{ [ STRING ':' ] expr }

[ [ FRAME ':' ] expr ]
[ [ PLAY ':' ] true | false ]

[ { BOOLEAN ':' expr } ]
[ { DOUBLE ':' expr } ]
[ { FLOAT ':' expr } ]
[ { INTEGER ':' expr } ]
[ { LOOKUP ':' expr } ]
[ { NULL ':' expr } ]
[ { PROPERTY ':' expr } ]
[ { REGISTER ':' expr } ]
[ { STRING ':' expr } ]
[ { UNDEFINED ':' expr } ]

[ [ TARGET ':' ] expr ]

[ REGISTER ':' ] expr

[ URL | TARGET ':' ] expr, expr
[ METHOD ':' ] expr

[ [ FRAME ':' ] expr ]
{ expr }
... play once frame loaded ...

ACTION "WAIT  FOR  FRAME" {
	"motorbike";
	ACTION "PLAY";
}

Please, see the LIST object below.

Creates a button (end user interaction). Any button can be composed of multiple STATE, (when to display such and such edit text, shape, sprite or text) and ACTION, (what to do on a proper click). Actions include LABEL, FUNCTION and WITH instructions as well. It is possible to define a list of actions to execute on a given set of events. This is done using an ON EVENT instruction.

If you want to create a menu, set the menu flag to true. The menu flag is useful to allow users to drag the mouse between different objects that pops up and out.

[ MENU ':' ] expr
{ expr }

The CATCH instruction is an action which encapsulates other actions. It is used to define an exception handler within a TRY block. Please, see the TRY reference for more information.

The CATCH needs to be named with either an alphanumeric name or a register number between 0 and 255. The exception being thrown will be saved in the named variable or the specified register. You can later use the GET VARIABLE action (in case you used a name) or the PUSH DATA action with 'register: <no>' to read the error from the register.

{ expr }

The CATCH actions are executed when an exception occurs while executing the actions defined in the TRY block.

Accepts only one list of three or four values representing colors. The expressions represent the luminance of the red, green, blue and optional alpha. When the alpha is not defined, it is supposed to be a solid color.

expr ',' expr ',' expr [',' expr]

Accepts one or two lists which represent how much to add to the color and how much it will be scaled by. The values to add must be labeled with ADD and the scaling factors by SCALE or MULT[IPLY]. The lists will be composed of three or four expressions to transform the red, green, blue and alpha parameters of a color respectively. When the alpha isn't specified, the default add is 0 and the default scale is 1.0. Only one of the field can be specified.

[ ADD ':' expr ',' expr ',' expr [ ',' expr ] ]
[ SCALE ':' expr ',' expr ',' expr [ ',' expr ] ]

This object expects a list of actions to execute unconditionally (though there can be conditions within the actions). A list of actions is composed of the following objects:

• ACTION,
• LABEL,
• FUNCTION,
• WITH.

[ ID | INIT[IALIZE] |INITIALIZATION ':' ] expr
{ expr }

DO ACTION { ACTION "STOP"; };

Accepts one or more list of:

• Two expressions which define a line edge.
• Four expressions which define a 2nd degree spline curve edge by defining a control point and an anchor.
• One labelled expression to specify a rotation angle. The order is important, only the last rotate is taken in account for the following edges.

These lists of two or four expressions are separated by semi-colons so as to defined multiple edges.

The last entry can be defined with the label CLOSE in which case it will be given the start coordinates automatically. The last two expressions following the CLOSE label are ignored. It is vital to close a shape which needs to be filled.

{ [ CLOSE ':' ] expr ',' expr [',' expr ',' expr] }
{ ROTATE ':' expr }

A new position in a set of edges definitions are always relative to the previous position. The first position is relative to the last MOVE of the object including these edges (or the object origin when there wasn't a MOVE). This also applies to the control points and anchors. That is, the position of an anchor is relative to its control point (say p defines the previous point, c the control point and a the anchor with standard 2 dimensional coordinates, the edges values to represent c are: c - p, and for a it is: a - c). In order to avoid these side effects, one can use the POINTS object instead.

In Flash movies it is possible to ask the user to enter information. These information will be typed in text areas. These are defined with the EDIT TEXT. An edit text is a very complex text that one can define in great details. The following gives you a complete list of the options available with that object.

[ WORD[_]WRAP ':' expr ]
[ MULTILINE ':' expr ]
[ PASSWORD ':' expr ]
[ READ[_]ONLY ':' expr ]
[ NO[_]SELECT ':' expr ]
[ BORDER ':' expr ]
[ OUTLINE[S] ':' expr ]
[ HTML ':' expr ]
[ AUTO[_]SIZE ':' expr ]
[ MAX[[_]LENGTH] | LENGTH ':' expr ]
[ MARGIN | LAYOUT ':' expr, expr [ , expr, expr ] ]
VAR[IABLE] ':' expr [ , expr ]
[ INIT | START ':' expr ]
[ ALIGN[MENT] ':' expr ]
[ USED[_]GLYPHS ':' expr ]
[ USED[_]STRINGS ':' expr ]
{ expr }

The AUTOSIZE BORDER HTML MULTILINE NOSELECT OUTLINES PASSWORD READONLY and WORDWRAP are flags which can be set to true or false. All of these flags are mandatory. By default the word wrap and border flags are true and all the others are false.

Please see the Alexis' SWF Reference document for more info about the supported HTML tags.

The MAX_LENGTH parameter specifies the maximum length in character of the text entry. This is mandatory. The default is to not constrain the length.

The LAYOUT can be used to specify several parameters useful to define the layout of the font versus the rectangle where the text is displayed. The layout is composed of the left and right margin, and the mandatory indent and leading sizes. The layout entry is mandatory.

The VARIABLE gives a name to this edit text object (as a sprite). Changing the variable value changes the text being displayed and when the user types in new text, it is also copied in this variable. This entry is required.

The INIT defines the text used to initialize the edit text button. The default is none.

The ALIGNMENT can be one of LEFT, RIGHT, CENTER or JUSTIFY.

The USED_GLYPHS and USED_STRINGS will be used to make sure that the referenced font has the given glyphs defined. By default (if none of these two entries are defined), all the glyphs are taken. The USED_GLYPHS can be used to declare ranges with two characters separated by a dash sign as in "A-Z0-9". The special string "*" is taken as all the glyphs. The USED_STRINGS is usually very good if you have many but a "fairly" small finite list of strings to print within this EDIT TEXT object. The dash sign (-) has no special meaning with the USED_STRINGS. Because only one USED_STRINGS can be used, you need to concatenate the different strings you want to use as in:

UsedGlyphs: "A-Z"; UsedStrings: "My Name" + "Charles 3" + "Albert 1" + "Henri 4";

This example ensures that all the uppercase letters are included in the font. Then the lower case letters and digits necessary to write the concatenated string "My NameCharles 3Albert 1Henri 4".

To complete the definition, it is necessary to define a TEXT SETUP and a RECTANGLE.

This object can be used to mark the end of the tags. Note that the movie playback can't go beyond an end tag whatsoever. You can mark the end of the tags in a SEQUENCE or a SPRITE object.

Defines a list of (a) position and a (b) left and (c) right volume which can later be used in a SOUND INFO object. When no right volume is specified, the left is used for both channels.

[ VOLUME ':' ] expr ',' expr [ ',' expr ]

It is possible to create a movie which is a place holder of many definitions which is later included by other movies. This is useful, for instance, to declare a large font so it is used by different movies without having to include this large font within each movie.

The draw back is that an IMPORT instruction is necessary and this one uses a URL. This means a dependency which is not automatically good to have on the Internet for many reasons. Yet, this draw back isn't major in comparison to the incredible time saving you can have using this feature.

The EXPORT instruction will include a list of pairs composed of one reference to a definition and one string which is the externally visible name for that definition.

ID | OBJ ':' expr ',' expr

Only definitions can be included in an export instruction:

• BUTTON
• EDIT TEXT
• FONT
• SHAPE
• SPRITE
• TEXT

There are three different types of fill styles:

• A solid fill (SOLID) which accepts a COLOR.
• A gradient fill (RADIAL or LINEAR) which accepts a GRADIENT and a MATRIX.
• A bitmap fill ([HARD-EDGE^*] CLIPPED or [HARD-EDGE^*] TILLED) which accepts an IMAGE and a MATRIX.

When the fill is used for a morph shape, then the different types of fill styles becomes:

• A solid fill (SOLID) which accepts two COLORs.
• A gradient fill (RADIAL or LINEAR) which accepts two GRADIENTs and MATRICES.
• A bitmap fill ([HARD-EDGE^*] CLIPPED or [HARD-EDGE^*] TILLED) which accepts one IMAGE and two MATRICES.

* note that the HARD-EDGE option generates a Flash animtion version 7.0

The TYPE of fill is specified with a string. This string can be one of the following names:

	"clipped"		(bitmap)
	"tilled"		(bitmap)
	"hard-edge clipped"	(bitmap)
	"hard-edge tilled"	(bitmap)
	"solid"			(color)
	"radial"		(gradient)
	"linear"		(gradient)
	"reset"			(to remove the fill in a shape)

Other strings will make the fill style generate an error. When no name is specified, the type of fill will be deduced automatically however, in some cases it won't get it right. Also, by defining the type of your fills you ensure you get that type. In other words, if some parameters are not compatible with that type, the system generates an error.

NOTE: naming the objects you are inserting in your fill styles is usually equivalent to entering the fill type as a string as described here. (1) gradients can be named "radial" or "linear"; and (2) images can be named "clipping".

It is possible, for morphing shapes, to define solid, gradient and bitmap morphing fills. In this case, the solid fill will have two colors and both, the gradient and bitmap fills will have two matrices. The order matters. Note that for bitmap fills you don't have two images.

expr [',' expr]
ID | IMG ':' expr
[ TYPE ':' ] expr

The representation is one or two expressions which can either be a reference to another object or a direct definition of that object.

IMAGE "clipping" { };
FILL STYLE "fill_clipping" {
	MATRIX { SCALE: 20, 20; };
	IMG: clipping;
};

The FINALLY instruction is an action which encapsulates other actions. It is used to terminate a TRY block. Please, see the TRY reference for more information.

{ expr }

Whatever happens in the corresponding TRY and CATCH blocks, the FINALLY actions are always executed.

Creates an SWF font. This is a list of glyphs or shapes that the following text definitions can reuse. The scripting language will automatically remap the characters in the text strings so you don't need to know how the glyphs are mapped. At this time the order in which the glyphs are included defines the mapping. This may change in the future and the order should not be taken in account.

{ ID | CHAR ':' expr ',' expr [ ',' expr ] }
[ LANGUAGE ':' expr ]
[[ NAME ':' ] expr ]
[ TYPE ':' expr [ ',' expr [ ',' expr [ ',' expr [ ',' expr ]]]]]
[[ LAYOUT ':' ] expr ',' expr ',' expr [ ',' expr ]]
[ ADVANCE ':' expr ]
[ SPACE ':' expr ]
[ { [ KERNING ':' ] expr ',' expr } ]

• A new character is defined with an ID or CHAR introducer, a character name (a one character string), a reference to a GLYPH or a SHAPE and an optional character specific width. The following defines the upper case character 'a':

  CHAR: "A", my_font_upper_a, 100;

  NOTE: don't forget that a reference is case insensitive; thus you need to distinguish upper and lower case letters better than in: my_char_a and my_char_A which actually reference the same object. One way to do so is to define all the lower cases in one list and all the upper case letters in another.

• A font can be NAMEd. The name will possibly be used by the player to determine whether the font is available on the running system. If so that font may be used instead of the internal one. The font name is a string.

• So as to pick the proper system font you need to define which type has to be used. The type is a list of 1 to 5 strings. The following are currently accepted: ANSII, SHIFT-JIS, UNICODE, BOLD, ITALIC and WIDE. Only one of the ANSII, SHIFT-JIS and UNICODE should be defined within one font.

• Starting with version 6.x, you can specify a language for the font (defining the language will force a v6.x movie). The available languages (case insensitive) must be specified in a string and can be any one of the following:
  • Locale
  • Latin
  • Japanese
  • Korean
  • Simplified_Chinese
  • Traditional_Chinese

• For font definitions in V3.0+ one can define a complete LAYOUT. This is done by defining 3 or 4 values which represent the ascent, descent, leading height and advance. The advance can also be specified by itself in which case it is taken in account in the TEXT objects but doesn't generate a layout in the font.

• The ADVANCE is used to specify the width of all the characters, except those which have a specific width. It can also be defined using the LAYOUT label. It is possible to define the width of the SPACE character without having to define it as a GLYPH. This saves some space since (a) the final text strings won't include a space and (b) there is no need for a glyph to draw nothing (this only holds if no TextFields are used). The value specified with the SPACE label is ignored if also a space (" ") glyph is defined.

• Finally, a set of KERNING entries can be defined. These are defined with a two character string (such as "AV") and an adjustment value. For instance, the character "A" may have a width of 100. However, when "AV" is written, a width of 90 could be more appropriate. This is done by including a kerning as follow:

  KERNING: "AV", -10;

The FOR will be used to generate a long list of entries. This could be avoided once the complete set of action expressions are supported. At this time, this instruction is particularly useful to declare a set of PLACE OBJECT and SHOW FRAME. Note that these two objects will be the most common within a FOR loop, yet this object doesn't test what it includes and thus really anything can be defined within the loop.

The result is viewed as a list of the objects repeated as expected.

FOR '(' IDENTIFIER '=' expr ';' expr ';' expr ')'
	'{' object_definition '}'

At this time, the last expression must only be an expression and should not be:

IDENTIFIER '=' <expr>

The following is an example which makes the movie pause for 60 frames:

    for(i = 0; i < 60; i + 1) {
	show frame;
    }

The FRAME LABEL will be used in order to compiled a named frame within the final movie. This can be used as an anchor in v6.x. It can also be useful in some scripts when you need to reference a frame within a Push data.

The FRAME LABEL only accepts a name. If the name starts with a hash sign (#) then it is taken as an anchor. The hash sign is removed from the name before the movie is saved.

The FUNCTION instruction is an action. Use it to declare a function which you can later call with a CALL FUNCTION action. The name of the function (which is the name of this object) can include a list of variable names separated by commas as in:

    function "wait(seconds, useconds)" { ... }

Within the curvly brackets you can include any type of action and since version 1.7.0, you can also include the definition of another function. It is possible to create unnamed functions which are pushed on the stack and can later be assigned as methods to object.

Since version 1.7.0, you can (1) assign function parameters to registers, (2) define the maximum number of registers you will be using and (3) define special registers to be either preloaded and suppressed.

The special registers are this, arguments, super, _root, _parent and _global. There is one special name which is _registers; it can be followed by the total number of registers used by this function. Note that in SWF Version 7, the players are supposed to make the registers local to each function.

Specify the register number (or number of registers in case of _registers) by following the variable name with a colon (:) and a number in decimal as in:

	function "foo(_registers:12, this, _root, param:3)" { ... }

Note that the player will automatically save the system variables in registers (such as this and _root). Thus, you don't need to specify a register number for those (on the other hand, it can help you know what goes where.) In this example, this will be saved in register 1, _root in register 2 and param in register 3 as specified. The _registers specification says that the function should reserve 12 registers to run properly.

The assignment of register numbers to the system variables is done in this order only (i.e. the order in which you specify these special registers doesn't matter):

• this
• super
• _root
• _parent
• _global

Only the system variables which are specified are allocated in registers. Thus, if you only specify this and _global, only register 1 and 2 will be taken.

Important notes: (a) if you define one of your parameters with a register number which is to be used by a system variable then its content will be overwritten by the content of the corresponding system variable; (b) if is possible to use the special register 0 for user variables so SSWF automatically allocates the proper registers for you; only problem: it doesn't tell you what these registers are, but in a later version, you will be able to specify the name of the parameter in a PUSH DATA with the type register and it will convert the name to the corresponding register number as expected.

Finally, you can suppress the creation of system variables. This can save some execution time when playing back the animation since it won't have to allocate any resources for these variables (really, I don't see the point, but well... maybe I should try to write a player to understand why this is necessary...). You can suppress any of the this, arguments and super parameters. To do so, preceed their name with a slash as in:

	function "foo(_registers:12, /this, /arguments, _root, ignore:0)" { ... }

This function doesn't create this nor the arguments (which is why I call our user parameter ignore). Also, the parameter ignore will be given a register number automatically.

expr

A GLYPH is a SHAPE with some limitations. One will usually use a GLYPH instead of a SHAPE in order to create the shapes for a font.

It is composed of at most one RECTANGLE which defines the character bounding box. When at least one character has a bounding box, the FONT object will use a DefineFont2 tag.

The turtle can be moved and the FILL STYLE can be changed before each set of EDGES and POINTS.

There can only be one fill style. You can switch between having the FILL STYLE turned on or off (use an empty fill style to turn off the filling). There can't be any LINE STYLE. Note that this option may be turned off in a later version since it doesn't seem that it is necessary to have the fill style turned off and the style itself isn't used anyway.

Note that the order matters since it will be included in the specified order in the final shape object.

{ [ MOVE | OFFSET ':' ] expr ',' expr }
{ [ FILL0 ':' ] expr }
{ expr }

Gradients are composed of a list of pairs. The pairs are composed of one position (defined from 0.0 to 1.0 - it is also called ratio) and one COLOR. When a gradient is defined for a morph SHAPE, their will be two pairs of position and color. The order of the expressions matters for morph gradients. The first two expressions define what to expect at position 0 and the last two expressions what to expect at position 1.

It is also crutial to include a MATRIX (or two in a morphing gradient) in order to specify the rotation, scaling and translation information.

The type of gradient can be specified with its name or a TYPE in the FILL STYLE including it. A gradient can either be named "linear" or "radial". Other names will generate an error.

{ expr ',' expr [ ',' expr ',' expr ] }
expr [ ',' expr ]

You must have at least two pairs and at most eight. The order to define the position and color doesn't matter, however, in case of a morph it needs to be the same for the two pairs.

Conditional expressions can be added with the ?: operator. However it is at times necessary to either have only one expression accepted or multiple expressions in one go. For this purpose use the IF statement instead.

In order to avoid conflicts in the grammar it was decided that it is obligatory to have the curvely brackets around the blocks of expressions. This anyway enhance the readability of scripts so it isn't so bad, is it?

IF '(' group_expr ')' '{' expr_list '}'
	[ { ELSE IF '(' group_expr ')' '{' expr_list '}' } ]
	[ ELSE '{' expr_list '}' ]

It is necessary to specify the compression format and the name of a file containing an image. At this time only targa files are accepted as input images. If you can't create 32 bits targa images (images which include a mask) then you can specify two file names. The second file is taken as a greyscale image and used as the alpha channel of the 1st image.

The format is specified as a label and can be either JPEG or LOSSLESS[size].

When you create a JPEG image, it is possible to specify the output quality of that JPEG with the QUALITY label and a value from 0 to 1. The default is whatever the JPEG group uses (usually 0.75). Note that when you specify zero, the default value is used.

JPEG | LOSSLESS ':' expr [',' expr]
QUALITY ':' expr

When you have created one or more movies for inclusion in several different other movies, you can import the data from these movies with the IMPORT instruction.

This instruction accepts a list of names referencing the objects within the exporting movie (only one movie can be imported per IMPORT instruction.) Each name in the IMPORT list needs to match one name in the referenced movie EXPORT list of objects. It is possible to specify the type of object you are importing thus avoiding problems by checking whether the object can be used wherever you are to using it later. Like other definitions, IMPORT definitions need to appear before being used.

When you have created the movie for inclusion, you can also specify its FILENAME. The system may then use it to check the imported object and ensure it will work as exported. This is particularly useful for fonts. Note that the URL can't be used since on the development system it's very unlikely that it will work. Plus, it would be very slow to access the Network to read a file you probably have right there on your hard disk.

The movie to import is specified within the given URL label. It has to be a valid SWF movie with one EXPORT tag.

NOTE: an IMPORT, to be useful, will always be named since in order to access the data within you will need a proper name.

URL ':' expr
FILENAME ':' expr
{ NAME ':' expr [ ',' expr ] }

    1. Object Names

It is at times necessary to reference an object in regard to its frame number. This is done (a) by naming the object, or, (b) when the name needs to be dynamic, by defining a label prior to the object.

The expression is expected to be a string. The following is an example to show how a label is commonly used:

LABEL { strf("play_sprite%d", index) };
PLACE OBJECT { ... };

The PLACE OBJECT receives the name "play_sprite1", "play_sprite2", etc. as the index is increment.

Variables can't be labelled. Some objects such as a sequence can't be labelled.

It is an error to give two objects the same name.

    2. Action Script Labels

It is at times necessary to jump from one place to another in an action script. The different branch instructions will reuse the label name. It is an error to insert two labels with the same name. Labels can be defined before or after the given branch instruction(s).

In both cases a label is composed of one expression which needs to be a string:

expr

Defines the color and width of a line. The definition must be composed of one color and one width, or two colors and two widths when used for a morph shape in which case the order matters.

WIDTH ':' expr [ ',' expr ]
expr [ ',' expr ]

This object is composed of any other object or variable. It can be used as a repository of any type of object. The order matters in case you want to access a list of items using the array operator (expr '[' group_expr ']').

{ expr }

NOTE: a list is not an SWF object.

Composed of up to four entries each composed of one or two expressions. The entries must be labelled as SCALE, ROTATE, TRANSLATE or SKEW. All the expressions must be values. The scale values are ratios. If only one value is specified, then it is used to scale horizontally and vertically equaly. The rotate value is an angle (in radians by default.) A positive rotation angle will rotate the object counter clockwise from 3 o'clock. The TRANSLATE represents coordinates in pixels where the object is moved after it was scaled and rotated. The SKEW is to generate an italic like effect of shapes. You should avoid using SKEW and ROTATE at the same time. I'm not too sure right now how to describe the type of value that SKEW uses. You should use a value between -2.0 and +2.0. The default is 0.0. To get some nice italic, a value of about -0.3 is usually enough.

SCALE ':' expr [ ',' expr ]
ROTATE ':' expr
TRANSLATE ':' expr ',' expr

WARNING: use ON EVENT in a PLACE OBJECT which reference a sprite only.

The ON EVENT declaration will be used in a PLACE OBJECT or a BUTTON object.

Composed of any action entry, events and key codes. The following entries must be labelled: EVENT[S] and KEY[[_]CODE]. The events must be defined in a string. The string can either represent a value (decimal, hexadecimal or octal) or a list of comma separated names. There are still some events I'm not sure of, and some which just don't seem to have any effect. The key code is a letter or a name.

The valid events are listed below. The value defined in the PlacObject2 column defines the value you can specify in SSWF. The comment is what I have found. Please, let me know if you find something else! Thank you.

The following lists the named keys. Other keys can be accepted when you enter a one character string. Note that only 7 bit ASCII keys are accepted and that's not international at all! (yet the addition of the key was made in v6.x...)

For more information about the available actions, please see the DO ACTION.

EVENT[S] ':' expr
KEY | KEY_CODE | KEYCODE ':' expr
{ expr }

WARNING: if you specify a name, it is likely that you need to use a REPLACE OBJECT instead.

Composed of different entries which all accept one expression. The following entries must be labelled: DEPTH, CLIP, MORPH, TAB_INDEX and ID. The expressions must be values, objects or a string for the name. The object references (labelled with ID) can be to a shape, sprite or text. The following other objects can be inserted: a MATRIX, ON EVENT, and a COLOR TRANSFORMATION.

A place object can include only one of a shape, sprite or image. Each of the other entries (depth, clip, morph, name, MATRIX and COLOR TRANSFORMATION) can be included only once.

Because of the way the COLOR TRANSFORMATION works, our scripting language also accept plain COLOR inclusion. These are automatically converted into a corresponding COLOR TRANSFORM with all scale factors set to 0.0 and add values to the given color values.

The CLIP value indicates how many depth from this object depth will be clipped by this object (WARNING: this is different from the encoded result which uses a hard coded depth as the inclusive maximum depth).

DEPTH | LAYER ':' expr
[ CLIP | CLIPPING ':' expr ]
[ MORPH | POSITION ':' expr ]
[ [NAME ':'] expr ]
[ TAB[_]INDEX ':' expr ]
ID | OBJ ':' expr
{ expr }

Accepts one or more list of:

• Two expressions which define a line coordinates.
• Four expressions which define a 2nd degree spline curve set of coordinates by defining a control point and an anchor.
• One labelled expression to specify a rotation angle. The order is important, only the last rotate is taken in account for the following edges.

These lists of two or four expressions are separated by semi-colons so as to defined multiple points.

The last entry can be defined with the label CLOSE in which case it will be given the start coordinate automatically. The last two expressions following the CLOSE label are ignored. It is vital to close a shape which needs to be filled.

{ [ CLOSE ':' ] expr ',' expr [',' expr ',' expr] }
{ ROTATE ':' expr }

A new position in a set of points definitions are always relative to the position of the origin (the position given to the object including these points). This also applies to the control point and anchor of a curve. In order to avoid the side effects, one may use the EDGES object instead.

Rectangles are defined with two pairs of coordinates. The coordinates are defined as the horizontal (x) position and the vertical position (y). The system will automatically save the coordinates as required (the smallest position first).

expr ',' expr ',' expr ',' expr

The order of the coordinates is (min-x, min-y, max-x, max-y).

Define either the object to be removed or the depth at which the object to be removed currently resides. An object reference is either a string or an identifer. A depth is a value. The script allows multiple objects to be specified within a REMOVE for faster coding. The resulting SWF will generate one REMOVE per object. When multiple objects have been inserted at a given depth, then only the last one inserted is removed. An object reference is optional. When only a depth is specified, the last object inserted at that depth is removed. This uses the RemoveObject2 tag (SWF V3.0).

[ DEPTH | LAYER ':' ] expr
[ { ID | OBJ ':' expr } ]

The use of the REPLACE OBJECT is similar to the PLACE OBJECT. The main difference is that the MOVE flag in the PlaceObject2 object will be cleared. This means an object should always be specified with a REPLACE OBJECT entry.

At this time the use or not of the MOVE flag doesn't seem to affect the behavior of the players.

The SCRIPT LIMITS tag defines the limits used by the player to ensure that a script doesn't overrun the system on which it is executed. You can specify the maximum number of recursive function calls and how long a script has the right to execute before an error is generated by the player.

All the accepted expressions in a script limits object:

MAX_RECURSION_DEPTH | MAX | RECURSION | DEPTH ':' expr
TIMEOUT_SECONDS | TIMEOUT | SECONDS ':' expr

A sequence is similar to a list. It can include all the objects which are valid for a sequence playback in an SWF file. At this time, this is the only SWF object with the SPRITE which accepts all the display list commands such as SHOW FRAME. The order matters.

{ expr }

The sequence object can include a special variable named frame_rate or framerate which will be used to setup the frame rate of the movie. By default, a rate of 30.0 will be used. Any value between 0.0 and nearly 256 (255.99609) can be specified. The precision of this value is a fixed 8.8 bits (8 bits before the decimal point and 8 bits after). The special strings "PAL" or "NTSC" can also be used in which case 25.0 or 30.0 will be used respectively.

References a solid color. At this time, if you try to use a transparent color as the background color, an error is generated. It is possible to directly define a color with a set of three values as you would define a COLOR object without an alpha channel.

expr

expr ',' expr ',' expr

Defines the depth of an object and its order in the list of objects to to be accessed whenever the end user hits the tab key. Note that the PLACE OBJECT also accepts the TAB_INDEX definition. It will then define two tags: a PLACE OBJECT and a SET TAB INDEX.

DEPTH ':' expr
TAB[_]INDEX ':' expr

Shapes are composed of one or two rectangles, multiple displacements, styles, edges and morph information. Shapes are used to draw objects on the output screen in a static way. It is possible to draw shapes in a fully dynamic way using action scripts.

The order in which these parameters are defined does matter.

The displacement is a set of two values eventually labelled as MOVE. The first displacement is always given from the origin (0, 0) [note that the origin position of a shape on the screen is given by a PLACE OBJECT].

The rectangles, styles and edges are either references to RECTANGLE, FILL STYLE, LINE STYLE, EDGES, or POINTS objects or direct inclusion of such objects. All of these objects can also be specified in sub-lists (see LIST for more information about lists).

The rectangles define the bounds where the shape is drawn. It is used for clipping purposes and must include the whole shape. WARNING: the anti-aliasing is drawn on an extra pixel and thus the clipping area needs to include that extra pixel. The players don't change the bounds you specify for their clipping purposes. The clipping rectangle can automatically be shown with the use of the SHOW_BOUNDS label set to the value true. This is useful to ensure that each shape is properly clipped. Also, if you need the resulting shape to be centered, use the SHOW_ORIGIN as well. If your shape is a morphing shape, then two rectangles can be defined. The rectangle of shape 0 and the rectangle of shape 1. If only one rectangle is defined for a morphing shape, then it is used for both shapes.

There can be at most two fill styles and one line style specified at a time. By default, a FILL STYLE is used as the first fill style (i.e. Fill #0). It is possible to specify a second FILL STYLE using the FILL1 label.

The number of MOVE, EDGES and POINTS isn't limited. These three operations are used by morphing shapes. In order to select what goes where, the MORPH flag will be used with 0 for shape 0, 1 for shape 1 and 2 for both shapes.

The following script shows you how to setup a simple morph. (you can find the complete example in the morphing sample coming with SSWF.)

fill style "fill_black_to_yellow" { sswf.col.black, sswf.col.yellow; };
line style "line_red_to_green" { 0.5, 1.5; sswf.col.red, sswf.col.green; };

define shape "morphing" {
	// use the same rectangle for both shapes (otherwise repeat)
	rect { -60, -60, 60, 60 };

	// the color goes from a black circle with a thin red edge
	// to a yellow square with a thicker green edge
	fill_black_to_yellow;
	line_red_to_green;

	// start both shapes at the same position (this is not a requirement)
	morph: 2;
	move: 0, -28.35;

	// draw shape 0
	morph: 0;
	circle_edges;

	// draw shape 1
	morph: 1;
	square_edges;
};

In order to turn off the current fill or line style, use an empty object of that type as follow:

FILL STYLE "no_fill" { };
SHAPE "helicopter" { ... FILL1: no_fill ... };

All the accepted expressions in a shape object:

{ [ MOVE | OFFSET ':' ] expr ',' expr }
{ [ FILL0 ':' ] expr }
{ FILL1 ':' expr }
{ SHOW[_]BOUNDS ':' expr }
{ SHOW[_]ORIGIN ':' expr }
{ expr }

Conceptually, if you consider that drawing a frame takes no time, a SHOW  FRAME tag will show the current frame on the screen, wait the amount of time one frame is supposed to be shown for, then proceed to the next frame (following tags until another show frame is found).

A good player will most certainly draw the following frame before to wait for a remaining amount of time. Then it possibly will skip some frames if necessary to keep the pace of the playback.

In order to repeat the SHOW  FRAME tag in the output file, one can specify a count value. By default the count is 1. Whatever value you specify, at least one SHOW  FRAME tag is always inserted. Use a FOR in order to conditionally insert or not a tag.

[ [COUNT ':'] expr ]

In order to playback a sound, it first needs to be defined with this tag. It is the only way to define a sound effect within a Flash movie except for the streaming sound effects.

At this time, a sound can be read from an uncompressed WAVE file only (also called PCM Wave).

[ [COUNT ':'] expr ]

Composed of a sequence. A Sprite is like a movie within the SWF movie. It is a limited sequence of display commands which can loop. Sprites are objects which can be placed using the PLACE OBJECT within a SEQUENCE. A sprite can include sprite references using the PLACE OBJECT.

{ expr }

The following are the accepted references:

• DO ACTION
• FRAME LABEL
• PLACE OBJECT
• REMOVE
• REPLACE OBJECT
• SHOW FRAME
• SoundStreamBlock
• SoundStreamHead
• StartSound

NOTE: a sprite will also accept FOR, LIST and BLOCK when these include the objects listed above.

Defines the state of the following shape to be inserted in a BUTTON object. A states defines a set of flags, a depth, a MATRIX and an object.

The object can be an EDIT TEXT, a SHAPE, a SPRITE or a TEXT. The depth is applied within the button only and defines where the object is inserted in the display list of the button.

FLAGS ':' expr
DEPTH | LAYER ':' expr
ID | OBJ ':' expr
[ MATRIX ':' ] expr

You can insert any of the following four flags (add their value to obtain the proper combinaison):

Defines a text entry. A text is mainly a string (inserted as is) however you have to declare which font will be used (see FONT) as well as a color, the height to use to draw the characters and an optional offset from the origin. These setups are done with the use of a TEXT SETUP object.

NOTE: the font used with a TEXT must be defined within the final movie. If you want to use a system font, you need to use an EDIT TEXT instead. Note that an EDIT TEXT can be made READ ONLY and in that case it will be very similar to a TEXT object.

In the text object, you can also apply one MATRIX to rotate and scale the resulting text object. The matrix is as in a PLACE OBJECT.

A RECTANGLE should be defined. It represents the bounding box for clipping purposes (to know whether the text has to be redrawn). The rectangle is defined just like in a SHAPE.

Finally, you can specify a default advance value after the string. This can be used for fonts which don't declare the width of their characters. (i.e. ADVANCE: "Hello", 25;)

{ [ ADVANCE ':' ] expr [ ',' expr ] }
{ expr }

A TEXT entry can be composed of multiple TEXT SETUP and strings. A TEXT SETUP can include any of the following:

• a position (x [, y]),
• a COLOR
• a FONT reference and an optional height.

All entries are optional, but at least one is required.

[ MOVE | OFFSET ':' ] expr [ , expr ] ]
[ ID ':' expr [ , expr ] ]
[ expr ]

The system will automatically optimize positions as much as possible. Thus specifying them doesn't make any difference on the resulting movie sizes.

The TRY instruction is an action which encapsulates other actions which may generate an exception. Whenever an exception is generated, the current execution stops and the actions in the following CATCH are executed. When no exception occurs, the following CATCH is ignored. In all cases, when there is a FINALLY, it is executed before to exit the TRY block.

{ expr }

Note that at least one of CATCH and FINALLY is necessary right after a TRY. When both are defined, the CATCH must appear before the FINALLY.

The following is a simple example:

	try {
		action "push data" { integer: 0; integer: 0 };
		action "divide";
	};
	catch "err" {
		action "push data" { string: "err"; };
		action "get variable";
		// ... do something about the error
	};
	finally {
		// whatever happens, ensure "my_var" is 0 at the end
		action "push data" { integer: 0; string: "my_var"; };
		action "set variable";
	};

The WITH instruction is an action which will be used in order to avoid the old SET TARGET action. A WITH defines a name (taken from the stack) and a block of instructions to be executed in link with that named object. There can be up to eight levels of WITH after what the players are likely to fail. Any instruction referencing a variable, a property, etc. is first checked in the current WITH block, then in its parent, and so on up to the root. Setting a variable will create a new variable within that object if it doesn't exist anywhere else. A WITH includes a list of actions as defined in the DO ACTION instruction.

{ expr }

The scripting language won't tell you if you use more than eight levels of WITH. This is your responsability.

It is not possible to create a function in a WITH definition.

Identifiers are used to define different commands and variable names. Valid commands vary depending on the context, however all of them are recognized at any time. Thus, a command can't be used as a variable name.

Defines a value. Note that all values could be represented as floating points internally. Yet, the opposite happens, only integers are used in an SWF format. Thus, we keep floating points wherever it is best suited only. We therefore will transform an integer in a floating or vice versa depending on the use of the given value.

The unit is one of the following identifiers:

Define an object. These are reserved keywords. You can't reuse these words anywhere else. Note that though object names such as FILL_STYLE can also be written in two words: FILL STYLE (a space or a tabulation), only the whole is considered a reserved keyword. Thus you can still use FILL or STYLE as variable names (though this isn't recommended).

Defines a quoted string. A quote can appear within a string when preceeded by a backslash.

You can use one of these C/C++ or Pascal comment introducer to insert comments pretty much everywhere you can have a space. The few exception will either be noted or should be easy to figure out. The grammar below doesn't reference comments.

Any blank will be considered a separator. These are ignored and can appear between any other lexical element. Operators also seperate different lexical elements but these are not always available. The grammar doesn't reference spaces.

Most of the other characters represent an operator. Valid operators are described in the grammar below. Note that some operators are composed of two or three characters (such as '<=' and '>>>'), these characters must be followed by each others (no spaces allowed between them).

<operator> <integer>

<integer> <operator> <integer>

All the usual C/C++ integer operators function as expected. These operators are:

• +
• -
• !
• ~

• *
• /
• %
• +
• -
• <?
• >?
• <<
• >>
• ==
• != or <>
• <
• <=
• >
• >=
• &
• ^
• |
• &&
• ||

The additional operators are as follow:

• a ** b -- computes a power b, the result is an integer
• a >>> b -- computes (unsigned) a >> b; this is because we don't have a way to cast to unsigned types within the Scripting SWF language
• a !< b -- rotates all the bits (none are lost) in a of b bits on the left
• a !> b -- rotates all the bits (none are lost) in a of b bits on the right
• a ^^ b -- like ^ with boolean values; the main idea for this operator is to give it the proper priority and also to force the left and right operands to be tested as boolean values
• a .. b -- defines a range of indices; this is used in array references to ask the system to use item a to item b inclusive

<operator> <float>

<value> <operator> <value>

All the usual C/C++ floating point operators function as expected. These operators are:

• +
• -
• !

• *
• /
• +
• -
• <?
• >?
• ==
• != or <>
• <
• <=
• >
• >=

The additional operators are as follow:

• a ** b -- computes a power b, the result is a floating point
• a % b -- is accepted and works as fmod(a, b)

<operator> <string>

<string> <operator> <string>

<string> <operator> <integer>

The operators work on strings like you would expect in Java or BASIC and other similar languages. The following is a list of operators currelty supported:

• + a - change all the lower case characters in upper case
• - a - change all the upper case characters in lower case
• ~ a - swap all the lower case characters in upper case; and vice versa

• a + b -- concatenate two strings or a string and an integer (in which case the integer is transformed in a string -- the integer must be the right hand side expression)
• a & b -- concatenate two strings or a string and an integer (in which case the integer is transformed in a string -- the integer must be the right hand side expression)
• a <? b -- selects the smallest of a or b in (at this time) a non-collate comparison between the strings
• a >? b -- selects the largest of a or b in (at this time) a non-collate comparison between the strings
• a << b -- shift the characters of the string a to the left by b characters (b must be an integer); spaces are introduced at the end of the string
• a >> b -- shift the characters of the string a to the right by b characters (b must be an integer); the first character is repeated b times at the beginning of the string
• a >>> b -- shift the characters of the string a to the right by b characters (b must be an integer); spaces are introduced at the beginning of the string
• a !< b -- rotate the characters of the string a to the left by b characters (b must be an integer); characters going out at the beginning of the string are reintroduced at the end
• a !> b -- rotate the characters of the string a to the right by b characters (b must be an integer); characters going out at the end of the string are reintroduced at the beginning
• a <comparison> b -- compare the a and b strings; the comparison is done taking the case in account (thus "A" != "a" is true). All the comparison operators can be used and the result is encoding dependent. The operators are: == != <> < <= > >=.

a ? b : c

The ternary selection operator is not like in C/C++. The main different is that b and c don't need to be of the same type. Also, a can be either a string, an integer or a floating point value. A string is considered to be true when not empty.

( group_expr )

Enables you to write comma separated expressions to be grouped in order to force a certain priority on the evaluation of the expression.

For instance, a + b * c and (a + b) * c don't yield the same result.

value unit

The use of a unit after a value expression will define how the system should handle it. If you prefer to use a certain type of measurement, it can be useful. Internally, all the values will be saved in a specific form which is unspecified here. The resulting SWF files will usually use very specific units for each type of entry (position/size, color, frame speed, etc.)

a . b

Reference object or variable 'b' in object 'a'. In order to reference objects in this way you need to name them.

a [ b ]

Reference object number 'b' within the list (or block) named 'a'. The object at index 'b' doesn't need to be named. The first object in a list is at offset 0 (as in C/C++).

<name>([<expr_group>])

The function calls are as you would expect in C/C++. The list of expressions can be empty (no parameter to that function call). The <name> must be one of the following valid functions:

float acos(float angle);

float asin(float angle);

float atan(float angle);
float atan(float angle, float angle);
float atan2(float angle, float angle);

float cbrt(float value);

integer ceil(float value);

float cos(float angle);

float exp(float value);

integer floor(float value);

float log(float value);

float log10(float value);

integer rint(float value);

float sin(float angle);

float sqrt(float value);

float tan(float angle);

string strf(string format, ...);

integer strlen(string str);

boolean defined(string name);

any select(integer index, ...);