Made to Order Software Corporation Logo

Reference to the Scripting language for SWF

Back to the SSWF project home page Last updated on @DATE@
(Written by Alexis Wilke in 2002-2009)

Contents

Appendices


This project license

The entire SSWF project is covered with the MIT license as follow:


Copyright (c) 2002-2009 Made to Order Software Corp.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.



About this language

I created this language following a search on the Internet for a good tool to create SWF files (Flash animations for the internet). I couldn't find anything of value so I decided I had to create my own library and a set of tools in order to cope with the lack of free software in that area.

The idea of a script language is simple since the SWF files are sequences of rather simple events. It is obvious, when looking in depth in the SWF file format that it is often necessary to do repeatitive things which are better handled with a set of loops rather than a long list of tags. It can easilly be generated by a graphical tool, though it isn't automatically easy for an end user to say precisely what he wants when he needs to use dialogs.

This being said, the use of the scripting language isn't necessary. It is possible to only use the sswf library to create your own graphical interface.

Alexis Wilke
the author


Language Instructions & Syntax

Though the lexical and grammar tell you how you can write a script, it doesn't tell you what is legal. This chapter defines each possible entry as they can be written. It only describes the SSWF objects since expressions are very much like C expressions (I suppose you can find such documentation elsewhere.) Note that there are more expressions in SSWF than in C and handling the different types is slightly different. This is all explained in the chapter about the SSWF grammar for those who want to be on the edge.

The scripting language accepts two types of definitions: variables and objects.

In SSWF, setting a variable is as follow:

	variable name = value;

Note that the assignment operator := is also accepted.

Objects are defined by specifying:

  1. the type of the object (such as COLOR or SPRITE);
  2. an optional1 name (written between quotes);
  3. and an optional1 list of parameters and definitions compositing the object (written between curvly brackets.)

1 Some objects must always be named or have a certain number of parameters. Though the grammar defines object names and parameters as optional, this is not always true.

For instance, the following code defines the color named  White :

	color "White" { 255, 255, 255; };

The following table describes all the objects currently accepted by the SSWF compiler. The descriptions include all the possible fields that an object accepts.

Different objects have different flags defined below their name. These flags are described in the following list:

  1. [nothing] — objects which don't have any specific flags are expected to either be empty or have only direct parameters; a direct parameter is a possibly labelled value appearing in the list of parameters;
  2. direct — a tag which takes no parameter
  3. composed — composed objects can include other objects in their list of parameters;
  4. semi-composed — composed of objects and direct entries
  5. ordered — the list of parameters of this object must be defined in the final expected order; a few objects also are mostly ordered meaning that some of there parameters can appear anywhere;
  6. must be direct — you can't declare such an object in a list and then name the list to include that object somewhere else;
  7. must be named — this object always require a name; an error will occur if no name is specified;
  8. This is an action — because some actions are composed of sub-actions, these are defined as objects; this includes actions such as FUNCTION.

In the table below, optional parameters are written between square brackets ([ and ]). Expressions that can be repeated are defined between curvely brackets ({ and }). Lists of repeated expressions can be empty. Multiple items in a list have to be seperated by semi-colons.

The SSWF Objects
Object Fields SWF Version
ACTION
(must be direct and
also always be named)

Important note: we now support the ACTION SCRIPT object which is accepting action scripts written in Javascript. In general, it will be a lot easier to use. The main problem for you will be to test whether the version being used is what you wanted.
Note: Please, check out the Alexis' SWF reference for more info about the versions of the actions.

Defines one action. Actions will be included in a DO ACTION, a BUTTON object and since version 6, some other objects such as a sprite initialization script.

[ 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 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.

Action Accepted
Expressions
ADD [CAST]

<none>

AND

<none>

BRANCH [ALWAYS]

[ LABEL | GOTO ':' ] expr

Expect a string representing the name of a label within the list of actions. When this action is reached, the flow of actions continues at the action following the given label. (IMPORTANT: this is not a frame label but an action script label)

[BRANCH] IF TRUE

[ LABEL | GOTO ':' ] expr

Expect a string representing the name of a label within the list of actions. When this action is reached, the flow of actions continues at the action following the given label if the expression on the stack represents true. (IMPORTANT: this is not a frame label but an action script label)

CALL FUNCTION

<none>

CALL METHOD

<none>

CAST OBJECT

<none>

CATCH

This is a direct instruction: CATCH.

CHR

<none>

CONCATENATE [STRING]

<none>

CONSTANT POOL
{ [ STRING ':' ] expr }

This is a synonym for the DICTIONARY action. It seems to be more sensical to use CONSTANT POOL rather than DICTIONARY for a constant pool.

DECLARE ARRAY

<none>

DECLARE LOCAL VARIABLE

<none>

DECLARE OBJECT

<none>

DECREMENT

<none>

DELETE

<none>

DICTIONARY
{ [ STRING ':' ] expr }

Defines a dictionary for this DoAction or Button context. Note that since version 1.6.2, SSWF accepts CONSTANT POOL instead.

DIVIDE

<none>

DUPLICATE

<none>

DUPLICATE SPRITE

<none>

ENUMERATE

<none>

EQUAL [CAST]

<none>

EXTENDS

<none>

FINALLY

This is a direct instruction: FINALLY.

FUNCTION

This is a direct instruction: FUNCTION.

GET MEMBER

<none>

GET PROPERTY

<none>

GET TARGET

<none>

GET TIMER

<none>

GET VARIABLE

<none>

GOTO
GOTO EXPRESSION
GOTO FRAME
GOTO LABEL


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

Expect nothing or a string representing the name of the frame to go to and a flag to tell whether you want the movie to continue to playback. Though a name is given, the script will transform it into a frame number (shorter form of the GOTO instruction) whenever possible. When no name is specified, then it encodes the GOTO with the dynamic form. i.e. the name is expected on the stack. See the LABEL instruction for more information.

The GOTO by itself can be used so the script language uses the most appropriate form available.

Using one of the other forms forces the system to use that specific form of the goto (except if one doesn't specify a name in which case the GOTO EXPRESSION is always used).

The only way to make sure you are using a GOTO LABEL is to use that form of the action.

IF TRUE

Please see BRANCH IF TRUE.

IMPLEMENTS

<none>

INCREMENT

<none>

INT
INTEGRAL PART

<none>

LABEL

This is a direct instruction: LABEL.

LESS THAN [CAST]

<none>

LOGICAL AND

<none>

LOGICAL NOT

<none>

LOGICAL OR

<none>

MB CHR

<none>

MB ORD

<none>

MB STRING LENGTH

<none>

MODULO

<none>

MULTIPLY

<none>

NEW

<none>

NEW METHOD

<none>

NEXT FRAME

<none>

NUMBER

<none>

OR

<none>

ORD

<none>

PLAY

<none>

POP

<none>

PREVIOUS FRAME

<none>

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

In a script it is often necessary to use constant values. These are pushed onto the stack using the PUSH DATA instruction. The type of the data being pushed needs to be specified. Note that you can specify as many constant entries as you need in one go. The following gives you a list of the available data types in ActionScript and what you can use in SSWF:

  • BOOLEAN - expects true or false
  • DOUBLE - expects a value
  • FLOAT - expects a value
  • INTEGER - expects a value; a floating point is rounded to the nearest value
  • LOOKUP - expects the index in the current dictionnary
  • NULL - anything; the expression is ignored
  • PROPERTY - expects a string with the name of the property to be modified; the names can start by and include spaces ( ), underscores (_), periods (.) and it can include dashes (-); the names are listed below:
    • X - horizontal position of the object
    • Y - vertical position of the object
    • X SCALE - horizontal scaling percent of the object
    • Y SCALE - vertical scaling percent of the object
    • CURRENT FRAME - returns the current frame
    • NUMBER OF FRAMES - returns the total number of frames
    • ALPHA - the alpha level of the object
    • VISIBILITY - whether the object is visible (true or false)
    • WIDTH - the width in pixels of the object
    • HEIGHT - the height in pixels of the object
    • ROTATION - the angle of rotation in degree, clockwise from 12 o'clock
    • TARGET - returns the full path to the object as a target name
    • FRAMES LOADED - the number of frames already loaded
    • NAME - the name of the object
    • DROP TARGET - path to an object where this object was dropped
    • URL - the URL of this movie
    • HIGH QUALITY - whether the movie (or an object) is running in high quality
    • SHOW FOCUS RECTANGLE - whether the current button with the focus is shown with a rectangle drawn around it
    • SOUND BUFFER TIME - the clock on the currently playing sound(s)
    • QUALITY - low, medium or high quality mode
    • X MOUSE - horizontal position of the mouse pointer within the movie
    • Y MOUSE - vertical position of the mouse pointer within the movie
    • WTHIT - I'm not sure what this is for, it seems it is in link with sprites and their depth (WTHIT = What The Hell Is This?!?)
  • REGISTER - place on the stack the value currently saved in the specified register; there are four registers 0, 1, 2 and 3 only
  • STRING - expects a string, including an empty string
  • UNDEFINED - expects anything; the expression is ignored; a special undefined object will be pushed on the stack, useful to test whether a result is valid or not
RANDOM

<none>

REMOVE SPRITE

<none>

RETURN

<none>

SET LOCAL VARIABLE

<none>

SET MEMBER

<none>

SET PROPERTY

<none>

SET TARGET
[ [ TARGET ':' ] expr ]

Define the target to use for the following instruction. The expression usually is the name of a sprite which will be activated in some ways. When no expression is specified, the name of the target will be taken from the stack isntead. It is also possible to do a set target with an empty string. This resets the target to the main (root) stream of the movie. (as if the main movie was a sprite with an empty name).

SET VARIABLE

<none>

SHL
SHIFT LEFT

<none>

[U]SHR
SHIFT RIGHT [UNSIGNED]

<none>

START

<none>

Note that it is a good idea to add a START within the very first frame especially if you have a stop at the end of your movie. This is because this way a rewind will also automatically restart the movie playback.

START DRAG

<none>

STOP

<none>

Note that it is a good idea to stop sprites which don't need to be played back in loops.

Also, if you have a one time playing movie (i.e. you use a STOP at the very end) then you should put a START in the very first frame so a rewind automatically restarts the movie playback.

STOP DRAG

<none>

STORE REGISTER
[ REGISTER ':' ] expr

When outside of the FUNCTION stores the top of the stack in register number 0, 1, 2 or 3.

Since version 7 of SWF, it is possible, when using a new type of function, to use register numbers from 0 to 255.

Don't forget that this instruction doesn't actually pop the top of the stack. It can be used to save something temporarilly which will be reused in the expression a little later.

Prior version 7 of the SWF player, the registers where not saved between function calls. In other words, calling a function can result in destroying these registers (for C/C++ programmers: these were globals.)

You can reload the content of a register using the PUSH DATA action.

STRING

<none>

STRING EQUAL

<none>

STRING LENGTH

<none>

STRING LESS THAN

<none>

SUB MB STRING

<none>

SUB STRING

<none>

SUBTRACT

<none>

SWAP

<none>

THROW

<none>

TOGGLE QUALITY

<none>

TRACE

<none>

TRY

This is a direct instruction: TRY.

TYPE OF

<none>

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

Accepts a new URL (or an empty string) and a target, or just a method (GET, POST or NOVAR[IABLE]). The target can be set to "_level0" in order to specify a new SWF file as the URL. The special target "_level1" can also be used (for what... I dunno - it seems to be in link with overlay capabilities). If you want to go to a new page, like with a regular HTML anchor, as the target, use one of "_top" (remove all the frames) or "_self" (replace the current frame only). If you use an empty target, then a new window is created for the destination URL to be displayed.

When a method is specified, then the new GET URL2 action is used. This means the target and URL are taken from the stack. The method is saved within the tag and specify how to deal with the SWF variables and how it should be forwarded to the HTTP server.

USHR

Please see SHIFT RIGHT [UNSIGNED].

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

This instruction waits for either the indicated frame or the frame number as specified on the stack. If that frame was already loaded, then the instructions specified within the backets are executed.

Example:

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

This is a direct instruction: WITH.

XOR

<none>

ACTION SCRIPT
(one script)

The ACTION SCRIPT object enables you to enter a Javascript like program in an SSWF script. At the time this instruction is found, the lexer switch to a new mode which enables the reading of the action script written in Javascript code (for more information about the Javascript language supported by SSWF, please look at the Action Script Compiler documentation.) Once the action script closing brace is found, the SSWF lexer takes back over to parse what follows in the file. Note that means you need the same number of opening and closing braces in all your scripts which makes a valid script anyway, so it should be easy. The result of including an action script is the same as adding actions one by one. The main difference is that it is a lot easier to type complex expressions using a language like Javascript. Also, it will be really easy to manipulate objects. You can use an action script anywhere you would otherwise be able to add actions. Note that you can't mix actions and action scripts. Also, it won't be possible for now to insert more than one action script where you can put actions. This limitation is mostly a simplification, but it certainly is what most people want anyway.

Note that at this time, it is not possible to request the compiler to compile everything for a given version of Flash. It will compile everything for version 7. If you don't use some expression, you will be able to generate code which will work with older versions but really there is nothing garanteed. If you really need to use a specific version, you could first use an action script, look at the output (using swf_dump) and then replace the action script with the output which you modify to get the version you want.

7
BLOCK
(composed and
usually ordered)

Please, see the LIST object below.

n.a.
BUTTON
(semi-composed)

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 pop up and out.

[ MENU ':' ] expr
{ expr }
1
Color Transform: 2
Menu: 3
Conditions: 3
Blend: 8
Filter: 8




CATCH
(composed and ordered)
This is an action.

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.

7
COLOR

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]
1
COLOR TRANSFORM

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 ] ]
1
DO ACTION
(composed)

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:

and an optional sprite identifier (V6.0+ only).
[ ID | INIT[IALIZE] | INITIALIZATION ':' ] expr
{ expr }
The following is an example on how to stop the movie from playing:
DO ACTION { ACTION "STOP"; };
1
Init: 6
ABC: 9

EDGES
(ordered)

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.

1
EDIT TEXT
(semi-composed)

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 ] ]
[ ALIASING | THICKNESS_SHARPNESS ':' expr, expr ]
[ RENDERER ':' expr ]
[ GRID[[_]FIT] ':' 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.

IMPORTANT: the OUTLINES flag must be set to true if you are using internal outlines and to false if you want to use a system font.

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 ALIASING parameter defines the thickness and sharpness to be used to render the fonts. This may or may not be used by the system. Both values are floating points expected to be positive. Use 0.0 to let the system use its internal default.

The RENDERER is a number (0 or 1) defining whether the normal Flash animation rendering engine is used (0) or the new font rendering engine is used (1). The definitions from system.sswf can be used (FONT_RENDERER_NORMAL and FONT_RENDERER_FLASH.)

The GRID_FIT parameter defines whether the rendering happens as usual or snaps to pixels to try to avoid most of the antialiasing. This accepts a value from 0 to 2 (in SSWF version 1.8.2). You can use the definitions from system.sswf instead of typing a number (FONT_GRID_FIT_NO_GRID, FONT_GRID_FIT_PIXEL or FONT_GRID_SUBPIXEL)

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.

WARNING: There seems to be a problem with the use of a system font when that font doesn't exist on your system. At this time I do not know if it only happens with this object or whether others would also be affected too. Anyway, when it happens you get nothing in the text area.
4
Settings: 8
Aliasing: 9

END
(direct)

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.

1
ENVELOPE

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 ]
2
EXPORT

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:

5
FILL STYLE
(composed and ordered)

There are three different types of fill styles:

  • A solid fill (SOLID) which accepts a COLOR.
  • A gradient fill (RADIAL, LINEAR or FOCAL*) 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, LINEAR or FOCAL*) which accepts a dual GRADIENT and two 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 animation version 7.0

* note that the FOCAL option generates a Flash animation version 8.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)
	"focal"			(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", "linear" or "focal"; 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.

NOTE:

to clip a bitmap (though it really doesn't seem necessary) one can use an empty image with the special name clipping; thus one would declare the following:

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

and use the "fill_clipping" just before a corresponding "fill_image".

1
Alpha: 3
Hard Edge: 7
Focal: 8


FINALLY
(composed and ordered)
This is an action.

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.

7
FONT
(semi-composed)

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 ]
[ DISPLAY NAME ':' expr ]
[ COPYRIGHT ':' 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.

    It is possible to not define any characters in the font. In that case the NAME is mandatory and used to name the system font to load.

    IMPORTANT NOTE: Remember that a system font cannot be rotated. It can, however, be scaled and translated. But it is likely to be rendered on a pixel boundary and thus you won't be able to create very smooth movements with those.

  • 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 (i.e. a system font or device font.) If so that font may be used instead of the internal one. The font name is a string.
  • Since version 9, DISPLAY NAME can be used. This field is different from the NAME field in that it is not used to load the font. It is only the legal defining name.
  • Since version 9, a font can be given a license or COPYRIGHT.
  • 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.
    WARNING: to display a system font, you also need to set the OUTLINE to false in your EDIT TEXT definition.
  • 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;

1
Layout: 2
Unicode: 3
High resolution: 8
Alignment: 8



FOR
(composed and
usually ordered)

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;
    }
n.a.
FRAME LABEL
(direct)

The FRAME LABEL will be used in order to compiled a named frame within the final movie. This can be used as a web page 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.

3
Script: 5
Anchor: 6

FUNCTION
(composed and ordered)
This is an action.

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
5
Auto-registers: 7
GLYPH
(semi-composed and ordered)

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 }
1
Over 255: 3
GRADIENT
(semi-composed and ordered)

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", "radial" or "focal". Other names will generate an error.

Since version 8, we can setup a focal point. This is done by adding FOCAL and a position between -1.0 and +1.0, where 0.0 represents the center, -1.0 represents the left side and +1.0 is the right side.

{ expr ',' expr [ ',' expr ',' expr ] }
object [ ',' object ]
FOCAL : float

You must have at least two pairs and at most eight for an animation version 7 or less. If you run player version 8 or better, you can use up to 15 pairs of position & color. 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.

1
Spread: 8
Interpolation: 8
Focal: 8
9 to 15 pairs



IF
(composed)

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 '}' ]
Notes:

(a) the '}''s before the ELSE's are not followed by a colon;

(b) as a special case, an ELSE can be followed by an IF without having to put that IF within the curvely brackets;

n.a.
IMAGE

It is necessary to specify the compression format and the name of a file containing an image. At this time, targa and JPEG files are accepted as input images. If you can't create 32 bits targa or use JPEG 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]. It is suggested that you use JPEG if you use a JPEG image as input.

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
The LOSSLESS label can also be LOSSLESS8 to force a colormap image; LOSSLESS16 to force RGB555 and LOSSLESS32 to ensure the full range of colors are saved as is. Using LOSSLESS without a size lets the scripting tool decide which of the formats is best suited for the given image.
1
Independent JPG: 2
Lossless: 2
Alpha: 3


IMPORT

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. Like other definitions, IMPORT definitions need to appear before being used.

After the name, it is possible to specify the type of object you are importing. This way you can avoid problems by letting the system check whether the object can be used wherever you are using it. In some cases, the type is required (i.e. for fonts, sprite for a DoAction, shape for a Font Glyph, image for a fill style.) The type can be one of the following:

  • button
  • edit
  • font
  • image
  • shape
  • sound
  • sprite
  • text

Note that in some cases the type imported will be accepted but that is not a correct type here.

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 ] }
5
LABEL

    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
n.a.
LINE STYLE
(semi-composed)

Defines the styles of a line. This includes:

  • Width — the thickness of the line; use two for morphing shapes
  • Color — a solid color for the line; use two for morphing shapes
  • Fill Style — an image or gradient fill for the line (instead of the color); this is not supported with morphing shapes
  • Caps — the start and end caps names; if you indicate only one, it is used for both caps; The special value "none" means that it will look like a square and end exactly at the given positions; so this is like "square" without the additions of caps (caps have a length of Width / 2).
    • LINE_STYLE_CAP_ROUND (0)*
    • LINE_STYLE_CAP_NONE (1)*
    • LINE_STYLE_CAP_SQUARE (2)*
  • Join — how to join different line segments, and the miter join limit factor (float)
    • LINE_STYLE_JOIN_ROUND (0)*
    • LINE_STYLE_JOIN_BEVEL (1)*
    • LINE_STYLE_JOIN_MITER (2)*
  • Scale — whether to scale the line horizontally and vertically (boolean); if you indicate only one, both are set to the same value
  • Pixel Hinting — whether points should be drawn on physical pixels (boolean); keep to false (the default) if you intend to move your object slowly
  • NoClose — whether the start and end point are standalone or forming a closed shape (boolean)
* Defined in include/sswf/script/system.sswf

The minimum definition must be composed of one color and one width. For a morphing shape, two widths and two colors are necessary. Line fill using a fill style is not available for morphing shapes.

The other features are available with SWF version 8. It defines better how lines have to be rendered.

At times it is necessary to remove the line style for the next part of a shape. This is done with an empty line style: LINE STYLE "no_line" {};

WIDTH ':' expr [ ',' expr ]
CAPS ':' expr [ ',' expr ]
JOIN ':' expr [ ',' expr ]
SCALE ':' expr [ ',' expr ]
PIXEL[_]HINTING ':' exp
NO[_]CLOSE ':' exp
expr [ ',' expr ]
1
Over 255: 2
Alpha: 3
Morph: 3
Fill Style: 8
Caps: 8
Join: 8
Scale: 8
Pixel Hinting: 8
NoClose: 8










LIST | BLOCK
(composed and
usually ordered)

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.

n.a.
MATRIX

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
SKEW ':' expr ',' expr
1
METADATA

The METADATA object generates a TagMetadata. This is composed of one string with metadata information such as the title and description of your animation.

You must choose between one of the following possibilities. If you define a FILENAME and URL then the URL will be ignored. The order below defines the priority (Use FILENAME if defined, then XML and finally any other entry.)

  • nothing
  • Used without any fields, the Metadata generates a default title, description, type, etc.

  • FILENAME
  • Specify the filename of an XML file which you want to load as the animation description. This XML is expected to be well formed. You can use xmllint to test that your XML is proper. When the filename does not end with .xml and cannot be loaded as is, the library tries again with .xml appended.

  • XML
  • Defines a string composed of the XML information you want to save in the animation. This strings needs to represent proper XML as expected by Macromedia.

  • direct content
    • TITLE (dc:title)
    • DESCRIPTION (dc:description)
    • AUTHOR (dc:creator)
    • PUBLISHER (dc:publisher)
    • COPYRIGHT (dc:rights)
    • URL (rdf:about attribute)

    You can define one or more of these entries. In this case, these strings are simple strings (no XML tag.) The SSWF library will automatically generate the necessary XML tags to encompass this information.

    In this case, the <dc:type> is set to MovingImage and the <dc:format> is set to application/x-shockwave-flash.

    If you do not define a URL then the default http://sswf.m2osw.com will be used.

Inserting several of these fields will result in one of them being used and the others being ignored.

FILENAME ':' string
XML ':' string
TITLE ':' string
DESCRIPTION ':' string
AUTHOR ':' string
PUBLISHER ':' string
COPYRIGHT ':' string
URL ':' string
8
ON EVENT
(semi-composed)

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.

Name
(DefineButton2 equivalent)
Value Comment Version PlaceObject2 DefineButton2
ONLOAD 0x00000001 not available Execute the actions when the sprite is first loaded in the plug in. This is a good way to know when a given movie is available for playback. 5
ENTER_FRAME 0x00000002 not available Executed when the frame where the movie is inserted is entered (?) I'm not sure about this one yet. 6
UNLOAD 0x00000004 not available Executed when the sprite is being unloaded. I never could successfully try this event. 6
POINTER_MOVE 0x00000008 not available Executed when the mouse moves within this sprite. I could never make this work. 6
POINTER_DOWN 0x00000010 not available Executed on a pointer down event... Hmmm... the POINTER_PUSH is actually the pointer down event... 6
POINTER_UP 0x00000020 not available Executed on a pointer up event... Hmmm... the POINTER_RELEASE events are actually the pointer up events... 6
KEY_DOWN 0x00000040 not available A key was pushed. The action handler can use a Key object in order to know which key was pressed by the user. 6
KEY_UP 0x00000080 not available A key was released. The action handler can use a Key object in order to know which key was pressed by the user. 6
DATA 0x00000100 not available I still don't know what this is really for... 5
INITIALIZE 0x00000200 not available This is the Start Component Parameters ... End Component Parameters block defined in Flash. It should not be combined with any other event to be fully compliant (though it very much looks like it works anyway). 5
POINTER_PUSH
(OVER_UP_TO_OVER_DOWN)
0x00000400 0x0004 A mouse button was clicked over the sprite or button. Use the _xmouse and _ymouse properties to know where the click occured exactly (if you need to know). 5
RELEASE_INSIDE
(OVER_DOWN_TO_OVER_UP)
0x00000800 0x0008 The mouse button was released within the sprite where it was first pushed down. This is the event the DefineButton reacts on by executing the actions within that object. 5
RELEASE_OUTSIDE
(OUT_DOWN_TO_IDLE)
0x00001000 0x0040 The mouse button was released outside the sprite where it was first pushed down. This is usually viewed as the cancellation of the click. 5
POINTER_ENTER
(IDLE_TO_OVER_UP)
0x00002000 0x0001 The mouse pointer entered the sprite (the mouse button is not being pushed). 5
POINTER_LEAVE
(OVER_UP_TO_IDLE)
0x00004000 0x0002 The mouse pointer exited the sprite (the mouse button is not being pushed). 5
POINTER_DRAG_ENTER
(OUT_DOWN_TO_OVER_DOWN)
0x00008000 0x0020 The mouse entered the sprite while dragging another sprite. (didn't test yet) 5
POINTER_DRAG_LEAVE
(OVER_DOWN_TO_OUT_DOWN)
0x00010000 0x0010 The mouse exited the sprite while dragging another sprite. (didn't test yet) 5
KEY_PRESS
(key mask)
0x00020000 0xFE00 The key press event was available in v5 within the DefineButton2, it was added in v6.x in the event handler of the PlaceObject2. In either case, you need to also define the key with a KEY: expr entry. 5/6
MENU_ENTER
(IDLE_TO_OVER_DOWN)
0x40000000
(not available)
0x0080 The menu enter event is only available in the DefineButton2 handlers. The value 0x40000000 can be used in SSWF instead of the name (MENU_ENTER). 5
MENU_LEAVE
(OVER_DOWN_TO_IDLE)
0x80000000
(not available)
0x0100 The menu enter event is only available in the DefineButton2 handlers. The value 0x80000000 can be used in SSWF instead of the name (MENU_ENTER). 5

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...)

Name Value
NONE

This is not actually understood in SSWF. It is taken as the default if you don't specify a key code.

0
LEFT_ARROW 1
RIGHT_ARROW 2
HOME 3
END 4
INSERT 5
DELETE 6
BACKSPACE 8
ENTER 13
UP_ARROW 14
DOWN_ARROW 15
PAGE_UP 16
PAGE_DOWN 17
TAB 18
ESCAPE 19
SPACE* 20
* you can either use " " or "SPACE" for the space characters.

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

EVENT[S] ':' string
KEY | KEY[_]CODE ':' string
{ expr }
PLACE OBJECT
(semi-composed)

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).

The BLEND MODE can be one of the following strings: "NORMAL", "LAYER", "MULTIPLY", "SCREEN", "LIGHTEN", "DARKEN", "DIFFERENCE", "ADD", "SUBTRACT", "INVERT", "ALPHA", "ERASE", "OVERLAY" or "HARDLIGHT".

The CACHE BITMAP flag expects true or false. It is false by default.

DEPTH | LAYER ':' expr
[ CLIP | CLIPPING ':' expr ]
[ MORPH | POSITION ':' expr ]
[ [NAME ':'] expr ]
[ TAB[_]INDEX ':' expr ]
ID | OBJ ':' expr
BLEND[_]MODE ':'  expr
CACHE[_]BITMAP ':'  expr
{ expr }
1
Morph: 3
Events: see actions
Blend: 8
Cache: 8



POINTS

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.

1
RECT[ANGLE]

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).

1
REMOVE

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 } ]
1
REPLACE OBJECT
(direct)

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.

3
SCENE FRAME DATA
(direct)

Use the SCENE FRAME DATA to define raw data to be used by that scene/frame. At this time, you can specify a filename. It is loaded and used as the Scene & Frame Data.

FILENAME | DATA ':' expr
9
SCRIPT LIMITS
(direct)

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
7
SEQUENCE
(composed and ordered)

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 following is a list of special flags supported in the SEQUENCE block. Note that for most they have a command line equivalent, yet those defined in the file usually take precedence.

  • compress (compress = true | false;)
  • The sequence object can include a special variable named compress used to have the movie compressed (true) or not (false). Setting the compression to true forces the movie version to 6 minimum.

  • frame rate (frame_rate = <value> | "PAL" | "NTSC";)
  • 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.

  • maximum version (maximum_version = <value>;)
  • The sequence object can include a special variable named maximum_version or maximumversion which is used to make sure that the version of the output movie is no more than that version. If a higher version is required, then an error will occur. Note that the maximum version is not limited. This means you can use any value from 1 to 255, thought at this time not so many versions of Flash exist (at time of writing, valid versions are between 1 and 9). You can use 0 in which case the maximum version number is not constrained.

  • minimum version (minimum_version = <value>;)
  • The sequence object can include a special variable named minimum_version or minimumversion which is used as the starting point to compute the minimum version of a movie (unless a larger version is required as when you request a compressed movie which means the minimum version must be 6). Note that the minimum version is not limited. This means you can use any value from 1 to 255, thought at this time not so many versions of Flash exist (at time of writing, valid versions are between 1 and 9). You can use 0 in which case the minimum version number is not constrained (i.e. 1 for uncompressed movies, and 6 for compressed movies.)

  • protect (protect = true | false;)
  • The sequence object can include a special variable named protect used to select whether the resulting movie will include a PROTECT tag. This is a boolean flag which can be set to either true or false. By default this flag is true.

  • use network (use_network = true | false;)
  • The sequence object can include a special variable named use_network or usenetwork used to tell whether the movie, when played locally can access the network or not. By default, this flag is set to false meaning that an animation played locally will not have Internet or Intranet access. Note that this setting only applies in movies of version 8 or more. Older versions will ignore this flag and always allow network access.

    Note also that setting the flag to true or false has no effect on the minimum version required to save a movie (i.e. setting the flag to false should force the minimum required version to 8 since older versions do not support that setting.)

  • version (version = <value>;)
  • The sequence object can include a special variable named maximum which is used as the version of the output movie. If a higher version is required, then an error will occur. Note that the version is not limited. This means you can use any value from 1 to 255, thought at this time not so many versions of Flash exist (at time of writing, valid versions are between 1 and 9). You can use 0 in which case the version number is not constrained.

n.a.
SET BACKGROUND COLOR
(composed)

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
or
expr ',' expr ',' expr
1
SET TAB INDEX

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
7
[DEFINE] SHAPE
(composed)

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 }
1
Over 255 entries: 2
Alpha: 3
Morph 1: 3
Morph 2: 8
Hinting: 8
Caps: 8
Line fill: 8






SHOW FRAME
(direct)

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 ]
1
SOUND

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 (also called PCM Wave) or an MP3.

[ FILENAME ':' ] expr
[ FORMAT ':' expr ]
[ MONO ':' expr ]
[ SET[_]8[_]BITS ':' expr ]

FILENAME is a full path to a sound file to load in the SWF animation.

FORMAT is the format to use in the output movie. SSWF supports RAW (do not use!), UNCOMPRESSED (does not work with MP3), and MP3 (only works with MP3.)

MONO is a boolean value. When set to true (non zero) then the output is forced to mono (does not affect MP3).

SET 8 BITS is a boolean value. When set to true (non zero) then the output is forced to 8 bits (does not affect MP3 since MP3 must be 16 bits anyway.)

Note that sound effects read from a WAVE file will be adjusted to work with SWF. That means if their playback rate is wrong, it will change it to the next rate up. If the rate is larger than the largest supported by the SWF format, it will be clamped at that rate.

2
MP3: 4
Uncompressed: 4
Nellymoser: 6


SOUND INFO

Information about starting and stopping a sound effect.

ID ':' expr
[ STOP ':' expr ]
[ NO[_]MULTIPLE ':' expr ]
[ RANGE ':' expr ',' expr ]
[ LOOP ':' expr ]
[ [ ENVELOPE ':' ] expr ]

ID is the reference to the sound to start or stop.

STOP defines whether we want to start or stop the sound effect. Set to true to stop the sound effect. Note that if this field is set to true, the other fields are ignored.

NO MULTIPLE ensures that the same sound effect does not get started more than once.

RANGE is a set of variables used to define the start and end point to play from the source sound effect.

LOOP is the number of times the sound effect should be played.

ENVELOPE is one or more references to envelopes. At this time, SWF is limited to 255 envelopes per sound info. In this version

2
MP3: 4
Uncompressed: 4
Nellymoser: 6


SPRITE
(composed)

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:

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

1
STATE
(semi-composed)

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 (or-ing their value to obtain the proper combinaison--use include/sswf/scripts/system.sswf to get the definition of each flag):

Name
Definition
Value

Function
Hit Test
BUTTON_STATE_HIT_TEST
(0x08)

The bounding box of the referenced object represents the active area. i.e. the area which can be clicked by the end user. A buttons without at least one hit test state entry have really no effect and are rather useless.

WARNING: the only valid object for a hit test active area is a SHAPE. At this time, other objects will be accepted but the button won't be functional.

Up
BUTTON_STATE_UP
(0x01)

The referenced object is shown when the user is not pushing on the mouse button over any of its hit area.

Down
BUTTON_STATE_DOWN
(0x04)

The referenced object is shown when the user is pushing on the mouse.

Over
BUTTON_STATE_OVER
(0x02)

The referenced object is shown when the mouse pointer is over the button hit area.

To show the shape in all cases, use UP, DOWN and OVER together.

1
Color transform: 3
Filter: 8
Blend: 8


TEXT
(semi-composed and ordered)

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 ] }
[ ALIASING | THICKNESS_SHARPNESS ':' expr, expr ]
[ RENDERER ':' expr ]
[ GRID[[_]FIT] ':' expr ]
{ expr }

For more information about the ALIASING, RENDERER GRID_FIT entries, please read options of the same name in the EDIT TEXT tag definition.

WARNING:

There is a bug in the Macromedia plugins which forces each string to be separated by a setup. This is done automatically by the system whenever required.

1
Alpha: 3
Settings: 8

TEXT SETUP
(semi-composed and ordered)

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.

1
Alpha: 3
TRY
(composed and ordered)
This is an action.

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";
	};
7
WITH
(composed and ordered)
This is an action.

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.

5

SWF Tags

The SWF tags are all defined in details in the Alexis' SWF reference document.

It is important to understand that many of the objects defined as such in the Scripting SWF language are not directly mapped as tags in SWF. Also, you usually can't force the SSWF compiler to use a tag rather than another (i.e. a PLACE OBJECT may generate a PlaceObject or a PlaceObject2 tag in the final SWF output.) The compiler usually tries to use the one with the lower possible version or the one which compresses better (again, this can't currently be specified).


Conforming to an SWF version

The code will ensure that anything which is saved in an SWF file is versioned. Thus the resulting movie will have a version which is the minimum you need to ensure its proper functioning.

Now, you can ask the compiler to fail when a tag or an action of a version higher than what you want is required to compile your source file(s). This is done by adding the variable maximum[_]version directly in your main sequence as follow:

	sequence "main" {
		maximum_version = 4;
	};

You can also check the version with the swf_dump -m shell command.

This document doesn't specify much what version will be required when using such and such object. This is work to be done! You can, however, find all the information about versions in the Alexis' SWF Reference document.


SSWF Environment Organization

The following figure presents the organization of the SSWF project with the 4 libraries, the sswf compiler and the few tools coming with the project. The samples and documentation are not presented here.


SSWF Message Sequence Chart

SSWF reads a set of input files, converts them into Flash tags in libsswf tag objects and saves the result in a Flash animation. The following graph shows you the two main loops in the SSWF application. The Save() function will also loop through all the tags (not shown on the chart.)


Lexical

The lexical was simplified to a set of operators, identifiers and values. All the values can be specified in integer or floating point form. Also, values can be followed by a unit whenever possible.

The following table gives you the list of lexical available in the sswf tool.

Name Lex Comments
IDENTIFIER [A-Za-z_][A-Za-z_0-9]*

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.

VALUE [1-9][0-9]*
0[0-7]*
0[xX][0-9a-fA-F]+
[0-9]+\.?[0-9]*([eE][+-]?[0-9]+)?


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.

Note that integers can be specified in decimal, octal and hexadecimal. Floating points also accept exponents.

WARNING

When an hexadecimal value is followed by the 'cm' unit without a space, then the lexical will exclude the 'c' from the hexadecimal value. This may cause errors in some cases. A warning is generated when this occurs.

UNIT bc
cm
deg
fc
fpf
fps
fpm
grad
in
pr
px
rad
rt
tw












NOTE: the units are not currently supported.

The unit is one of the following identifiers:

UnitComments
bcByte color - a luminance value from 0 to 255
cmCentimeters - accepts a precision of 1.763888 × 10-3
degDegrees - angle in degrees (0 to 360)
fcFloating point color - a luminance value from 0 to 1.0
fpfFrames per field - accepts a precision of 0.234 in NTSC and 0.195 in PAL
fpsFrames per Second - accepts a precision of 0.0039
fpmFrames per Minute
gradGrade - angle in grade (0 to 400)
inInches - accepts a precision of 6.9444 × 10-4
prPercent - a value in the range of 0 and 100
pxPixels - accepts a precision of 0.05; when coordinates are defined, this is the default at start (it can be changed to another unit)
radRadians - angle in radians (0 to π × 2)
rtRatio - a value in the range of 0.0 and 1.0
twTWIPS - roughly a value with a precision of 1/20th of a pixel; this is the exat value which will be saved in a file

OBJECT Please see the list of objects in the index
at the top of this document. The lexical
correspond to the given word(s). When there is
a space it can either be written with a space
( ) or an underscore (_) character.



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).

STRING \"(\\\"|[^"])*\"
\'(\\\'|[^'])*\'
\`(\\\`|[^`])*\`

Defines a quoted string. Quotes can be any one of the double ("), simple (') and backward (`) quotes. A quote can appear within a string when preceeded by a backslash.

<comment> \/\*.*\*\/ (this is simplified here)
\(\*.*\*\) (this is simplified here)
//.*

You can use a comment pretty much everywhere you can have a space. The lexer understands C ( /* ... */ ), C++ ( // ... ) and Pascal ( (* ... *) ) comments. The few exception will either be noted or should be easy to figure out. The grammar below doesn't reference comments.

<space> [ \t\r\n\v\f]

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.

<operator> .

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).


Grammar

The following is a full description of the grammar of the SWF script language. Each possible term is defined here. The syntax follows the standard yacc syntax. If you look at it closely you will notice that the file as a whole is an expression and that's the way it is defined. This means some features uses this mechanism to setup information which could otherwise use variables in a possibly less straight forward manner. This is especially true for units. An expression can be defined with a unit. This means the file as a whole can defined to work in a specific unit as in:

	( <... whole file ...> ) tw

which specifies that all the values are in TWIPS, except those which don't accept such a unit and also these other expressions which have received a specific unit definition.

In the expr rule below, the operators are given in order of decreasing priority. However, the list given to bison or yacc is increasing. Also, the list at the beginning defines whether an operator is left (a + b + c => reduce a + b then add c) or right (a ** b ** c => reduce b ** c then do a ** (b ** c)).

	%left	'=' ':='
	%left	'?' ':'
	%left	'..'
	%left	'||'
	%left	'^^'
	%left	'&&'
	%left	'|'
	%left	'^'
	%left	'&'
	%left	'==' '!=' '<>' '<' '<=' '>' '>='
	%right	'<<' '>>' '>>>' '!<' '!>'
	%left	'<?' '>?'
	%left	'+' '-'
	%left	'*' '/' '%'
	%right	'**'
	/* in the following, +/- represent the positive & negative operators */
	%right	'+' '-' '!' '~'
	%left	'['
	%right	'.'
	%left	UNIT

	/**** START ****/
	start: expr_list opt_end

	/**** EXPRESSIONS ****/
	expr_list: block_expr
		| expr_list colons block_expr

	block_expr: expr
		| '{' expr_list '}'

	group_expr: expr
		| group_expr ',' expr

	expr:
		  expr UNIT
		| expr '.' expr
		| expr '[' group_expr ']'
		| '$' '(' group_expr ')'	/* complex variable reference */
		| '(' group_expr ')'
		| '+' expr
		| '-' expr
		| '!' expr
		| '~' expr
		| IDENTIFIER '(' ')'
		| IDENTIFIER '(' group_expr ')'
		| expr '**' expr		/* power */
		| expr '*' expr
		| expr '/' expr
		| expr '%' expr
		| expr '+' expr
		| expr '-' expr
		| expr '<?' expr
		| expr '>?' expr
		| expr '<<' expr
		| expr '>>' expr
		| expr '>>>' expr		/* unsigned shift */
		| expr '!<' expr		/* rotate left */
		| expr '!>' expr		/* rotate right */
		| expr '==' expr
		| expr '!=' expr
		| expr '<>' expr		/* like '!=' */
		| expr '<' expr
		| expr '<=' expr
		| expr '>' expr
		| expr '>=' expr
		| expr '&' expr
		| expr '^' expr
		| expr '|' expr
		| expr '&&' expr
		| expr '^^' expr
		| expr '||' expr
		| expr '..' expr		/* defines a range1 */
		| expr '?' group_expr ':' expr
		| IF '(' group_expr ')' '{' expr_list opt_end '}' opt_else
		| IDENTIFIER '=' expr
		| IDENTIFIER ':=' expr		/* like '=' */
		| object			/* in place definition */
		| IDENTIFIER
		| VALUE
		| STRING

	opt_else: /* empty */
		| ELSE '{' expr_list opt_end '}'
		| ELSE IF '(' group_expr ')' '{' expr_list opt_end '}' opt_else

	/**** OBJECTS ****/
	object: OBJECT opt_name '{' object_definition opt_end '}'
		| OBJECT opt_name '{' opt_end '}'
		| OBJECT opt_name
		| ACTIONSCRIPT opt_name '{' action_script '}'

	/* please, see the syntax below for a list of fields on a per object basis */
	object_definition: definition
		| object_definition colons definition
		/* IMPORTANT: some objects don't accept a list of fields */

	definition: IDENTIFIER ':' group_expr
		| group_expr
		| FOR '(' IDENTIFIER '=' expr ; expr ; expr ) { object_definition opt_end }

	/**** FLASH ACTION SCRIPT ****/
	action_script: javascript like code

	/**** COMMON RULES ****/
	opt_name: /* empty */
		| IDENTIFIER
		| STRING

	opt_end: /* empty */
		| colons

	colons: ';'
		| colons ';'
1 The left and right hand expressions of a range can only be a value or a string; identifiers must be references to variables of either of these types; both expressions need to be of the same type; ranges are currently only supported in array references.

The following defines the valid expressions and how the evaluator generates the result:

Typed Expression Comments
<operator> <integer>
and
<integer> <operator> <integer>

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

Unary
  • +
  • -
  • !
  • ~
Binary
  • *
  • /
  • %
  • +
  • -
  • <<
  • >>
  • ==
  • != or <>
  • <
  • <=
  • >
  • >=
  • &
  • ^
  • |
  • &&
  • ||

The additional operators are as follow:

Binary
  • a <? b — returns the smallest of a or b
  • a >? b — returns the largest of a or b
  • 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>
and
<value> <operator> <value>
where at least one of the <value> is a floating point value.

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

Unary
  • +
  • -
  • !
Binary
  • *
  • /
  • +
  • -
  • ==
  • != or <>
  • <
  • <=
  • >
  • >=

The additional operators are as follow:

Binary
  • a <? b — returns the smallest of a or b
  • a >? b — returns the largest of a or b
  • a ** b — computes a power b, the result is a floating point
  • a % b — is accepted and works as fmod(a, b)
<operator> <string>
and
<string> <operator> <string>
and
<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 currently supported:

Unary
  • + 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
Binary
  • 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:

Function prototype
& Description
Math Functions
float acos(float angle);

    returns the arc cosine of the input

float asin(float angle);

    returns the arc sine of the input

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

    returns the arc tangent of the input or inputs; atan2 must be used with two input; atan can be used with either one or two (in the latter the it behaves like atan2)

float cbrt(float value);

    returns the cubic root of the input

integer ceil(float value);

    returns the smallest integer not smaller than the input

float cos(float angle);

    returns the cosine of the input

float exp(float value);

    returns the neperian exponential of the input (e power <float>)

integer floor(float value);

    returns the largest integer not larger than the input

float log(float value);

    returns the neperian logarithm of the input

float log10(float value);

    returns the logarithm base 10 of the input

integer rint(float value);

    returns the integer the closest to the input

float sin(float angle);

    returns the sine of the input

float sqrt(float value);

    returns the square root of the input

float tan(float angle);

    returns the tangent of the input

String Functions
string strf(string format, ...);

    returns a formatted string; the format string is the same as an sprintf(3C) format string

integer strlen(string str);

    returns the length in characters of the input string

Other Functions
boolean defined(string name);

    search for <string>; return true if it exists as an object or a variable, false otherwise

any select(integer index, ...);

    use the integer as an index to select one item among the following list; the first item after the index is at position 1; using a negative or null index or an index larger than the number of items present in the select generates an error


This document was last modified on @DATE@.