Add (typed)

Pops two numbers or two strings, computes the sum or concatenation and push the result back on the stack.

This action is typed meaning that it will automatically convert the parameters as required and in a very well defined manner1.

• 1. I need to verify and make sure that the synopsis I give here is indeed correct.

Add

This action pops two numbers from the stack, add them together and put the result back on the stack.

IMPORTANT NOTE

This instruction is not compliant to the ECMA Script reference. It should only be used in SWF files using version 4. Since version 5, the Add (typed) action should be used instead.

And

Pop two integers, compute the bitwise AND, and push the result back on the stack.

Branch Always

Jump to the specified action. The offset is added to the current execution pointer as it is after reading the branch instruction.

IMPORTANT NOTES

The offset must be such that when added to the current execution pointer it points to a valid action (i.e. you cannot jump in the middle of a Push Data or any other multi-byte action.)

The offset cannot point outside of the current block of execution, although it can branch to the very end of the block. So if you are inside a With or Try block, a Branch Always cannot be used to exit that block. This can be a problem if you are trying to implement some advanced functionality in an ActionScript compiler such as a goto instruction.

Branch If True

Pop a Boolean value; if true then jump to the specified action; otherwise continue with the following actions.

There is no Branch If False action. Instead, first use the Logical Not, then Branch If True.

IMPORTANT NOTES

The offset, which is defined in bytes, must be such that when added to the current instruction pointer it points to a valid action (i.e. you cannot jump in the middle of a Push Data or any other such action.)

The offset cannot point outside of the current block of execution, although it can branch to the very end of the block. So if you are inside a With or Try block, a Branch If True cannot be used to exit that block. This can be a problem if you are trying to implement some advanced functionality in an ActionScript compiler such as a goto instruction.

Call Frame

Pop a string or integer and call the corresponding frame.

This means:

1. Search the corresponding frame,
2. Execute its actions, and
3. Continue with the action defined after this one.

The frame can be identified with a name or a number. It is also possible to specify a target movie ("<sprite name>.<frame name>"? - to be tested...)

Call Function

Pops one string that represents the name of the function to call, pop one integer indicating the number of arguments following, pop each argument, call the named function, push the result of the function on the stack. There is always a result1.

The concept of a function in SWF is the same as in most languages. The function uses its own stack and local variables and returns one result as expected. However, be careful because functions declared in a movie before version 7 could stack multiple results and they all were returned!

Since Flash 5, the players offer a set of internal functions2 available to the end user via this Call Function instruction. Please, see the internal functions table for a complete list.

• 1. When nothing is returned by the function, the result undefined is pushed on the stack.
• 2. These are internal objects with function members.

Call Method

Pop the name of a method (can be the empty string), pop an object, pop the number of arguments, pop each argument, call the method (function) of the object, push the returned value on the stack.

When the string is empty, the constructor is called. This is used by the system right after a new operator was called and most of the time the return value is simply discarded.

Cast Object

The Cast Object action makes sure that the object o₁ is an instance of class s₂. If it is the case, then o₁ is pushed back onto the stack. Otherwise Null is pushed onto the stack.

The comparison is identical to the one applied by the Instance Of action.

Chr (multi-byte)

Pop one integer, use it as a multi-byte string character code and push the newly created string on the stack.

The integer can be any number from 0 to 65535, although many codes are not valid characters.

For more information about valid characters, please, check out the Unicode Consortium.

Chr

Pops one integer, use it as a ASCII character and push the newly created string on the stack.

The function only works with ASCII characters: a number from 0 to 255, some of which will not work (especially 0).

To generate a USC character, use the multi-byte chr() instruction instead.

Concatenate Strings

Pop two strings, concatenate them, push the result on the stack.

Note that the second string is on the left hand side of the concatenation.

Declare Array

Pops the number of elements in the array. Pop one value per element and set the corresponding entry in the array. The array is pushed on the stack. It can later be sent to a function or set in a variable.

To set the indices, use the Declare Object instead.

Declare Dictionary

Declare an array of strings that will later be retrieved using the Push Data action with a dictionary lookup. There can be a maximum of 65534 strings. The visibility of a dictionary is within its DoAction or other similar block of actions. Note that you should have only one Declare Dictionary. The dictionary is visible from everywhere in the DoAction. In other words, you can access it from functions1, With blocks, try/catch/finally blocks, etc.

When multiple Declare Dictionary actions are used, only the last one found is in force when Push Data actions are encountered.2

Note that a Declare Dictionary is only useful for optimization. A Push Data can be used to push a string on the stack without the need of a Declare Dictionary. In other words, since it requires 2 or 3 bytes in a Push Data to retrieve a string, strings of 1 character are never needed in a dictionary. Also, a string used only once does not need to be in a dictionary. Finally, a Declare Dictionary action requires an extra overhead of 3 bytes3. So if the only thing you have to put in it is a rather small string used twice, again, it may not save you anything.

IMPORTANT NOTE

To ensure proper functionality, it is advised that you put the Declare Dictionary at the very beginning of your blocks of actions and use only one of them. With the limit of 65534 entries, you will first reach the size limit  of the Declare Dictionary and not unlikely of the block of actions. It is therefore not possible that you'd ever exhaust the available size offered by this action.

• 1. Declare Function and Declare Function 2 both accept accesses to Declare Dictionary.
• 2. I never tested in a loop. Side effects could very well happen in that case... it may use one or the other when you branch before a Declare Dictionary... TBD
• 3. One byte for the action code and 2 bytes for the size.

Declare Function (V7)

Declare a function which can later be called with the Call Function action or Call Method action (when defined as a function member.) The f_function_length1 defines the number of bytes that the function declaration uses after the header (i.e. the size of the actions defined in the function.) All the actions included in this block are part of the function body.

Do not terminate a function with an End action.

A function should terminate with a Return action. The value used by the return statement will be the only value left on the caller stack once the function return. When nothing is defined on the stack, null is returned.

Functions declared with this action code byte also support the use of up to 255 local registers (registers 0 to 254 since the f_reg_count byte specifies the last register which can be used plus one). To access the local registers, use the Push Data action with a load register and to change a register value use the Store Register action.

Also, it is possible to control the preloading or suppressing of the different internal variables: this, arguments, super, _root, _parent and _global. All the function arguments can also be ignored. If you write a compiler, you should preload only the variables which are used in the function body. And you should suppress all the variables that are never being accessed in the function body2. If you are writing a smart player, then you may want to avoid creating the variables until they are actually being used (thus when an if() statement ends the function prematurely, you may end up not creating and deleting many of these variables!)

The preloading bits indicate in which register to load the given internal variable. The suppressing bits indicate which internal variable not to create at all. That is, if the preloading bit is not set and the suppressing is not set, then the internal variables are supposed to be created by name (i.e. you can access a variable named "this" from within the function when bits 0 and 1 are zero.)

The f_reg_count parameter must be specified and it tells the player the largest register number in use in this function. This way it can allocate up to 255 registers on entry. By default, these registers are initialized as undefined. The variables automatically loaded in registers are loaded starting at register 1. The internal variables are loaded in this order: this, arguments3, super, _root, _parent and _global. Thus, if you call a function accepting three user parameters and uses the this and _parent special variables, it will load this in register 1, _parent in register 2 and the user parameters can be loaded in registers 3, 4 and 5. User parameters are loaded in registers only if their corresponding f_param_register field is not zero (see swf_params). Also, they don't need to be defined in order.

Note that system variables are loaded AFTER arguments. This means if you put an argument in register 3 and this register is also used for _root, then within the function the register 3 will be equal to the content of _root and the value of the argument won't be available to you. Compilers will know how to avoid this problem.

• 1. A function is limited to 65535 bytes.
• 2. WARNING: note that it is possible to concatenate two strings such as "th" and "is" to generate the name "this" and then do a 'get that variable'. This means a compiler cannot really know whether any of the internal variables are really never going to be used... but who writes code like that, really?!
• 3. WARNING: the registers used for the user arguments is defined in the swf_param structure, it does not need to be in sequence, but must be after all the other special variables.

Declare Function

Declare a function which later can be called with the Call Function action. The f_function_length1 defines the number of bytes that the function declaration takes. All the actions included in this block are part of the function. A function should terminate with a Return action. The value used by the return statement should be the only value left on the caller stack.

Do not terminate a function with an End action

Prior version 6, the Macromedia player would keep all the data pushed in a function as is when the function returned whether there was a Return action or not. This means some functions that worked in version 6 and earlier may not work anymore in newer versions.

Since version 7, it is preferable to use the new type of functions: Declare Function (V7).

This action is applied to the current target. This means you are indeed creating a function member that gets attached to the current movie (sprite).

• 1. Functions are limited to 65535 bytes in length.

Declare Local Variable

Pop a variable name and mark it as a local variable. If the variable does not exist yet, then its value is undefined. To declare and set a local variable at oncw, use the Set Local Variable action instead.

Declare Object

Pop the number of members that will be created in the object. Pop one value and one name1 per member and set the corresponding member in the object. The resulting object is pushed on the stack. It can later be sent to a function, saved in a register or set in a variable.

A declared object  is of type Object instead of being specialized by a specific class. This means the Cast Object will not be useful on such objects.

• 1. The member names are converted to strings; they certainly should be strings though anything is supported.

Decrement

Pop one number, subtract 1 from it and push the result back onto the stack.

Delete

Pop one string representing the name of the property to be deleted. Then pop the object from which the property is to be deleted.

In version 5 through 8, it is necessary to Push Data type undefined (0x03)1 before the string as in:

96 04 00 03 00 'a' 00 3A
delete("a");

to delete a global variable.

According to some movies I have looked at, the delete instruction returns some undefined value. In newer versions, though, the value is supposed to be a Boolean telling whether the object was really deleted (i.e. if false, then another reference is still present.)

• 1. Since player version 9, deleting a dynamic (global) variable requires _root (or _global) instead of undefined.

Delete All

Pop one string representing the name of the object that gets all of its variable members deleted.

Divide

Pop two values, divide the second by the first and put the result back on the stack.

The numbers are always transformed to floating points. Use the Integral Part action on the result to extract an integer.

Duplicate

Pop one item and push it back twice.

Note that it is a very good idea to use this action instead of duplicating data in a Push Data.

Duplicate Sprite

s₃ is the name of an existing sprite1 which is copied by this action.

The new sprite is given  the name s₂ and is placed at depth i₁.

The depth of a duplicated sprite is not used the same way in Flash 4 and Flash 5+. The depth parameter in this function is not clearly documented anywhere, but it looks like you need to have a depth of 16384 or more for a duplicated sprite to work properly (this is not visible to the high level ActionScript users.)

• 1. Remember that a sprite, movie, thread and other terms that I forget, are all the same thing.

End (action)

End a record of actions. There are no valid instances where this action is optional.

The End action itself as no meaning other than marking the end of the list of actions. Yet, if reached, the execution of the script ends and is considered complete.

IMPORTANT NOTE

This action ends a complete list of actions. Declare Function, With, try/catch/finally and other blocks of actions are never ended with this action. Instead, internal blocks have a size in bytes1 that is used to determine the end of the block.

This is different from the End tag that is used inside a Sprite to end its list of tags.

• 1. WARNING: two actions, Wait For Frame and Wait For Frame (dynamic), include a size in number of actions, not bytes.

Enumerate

Pop the name of an object and push the name of all of its children (methods & variables) back on the stack. The list is null terminated.

This mechanism can be used to implement a foreach() function on an object. Be careful, though, that the stack be 100% cleared when leaving the loop.

This action uses the name of an object. If you have an object reference, use the Enumerate Object action instead.

Enumerate Object

Pop an object from the stack, push a null, then push the name of each variable and function member of that object on the stack.

This mechanism can be used to implement a foreach() function on an object. Be careful, though, that the stack be cleared when leaving the loop.

This action uses an object reference. If you only have the name of the object, use the Enumerate action instead.

Note that internal functions, such as the play() function on a MovieClip1, are enumerated but they cannot really be dealt with easily. Their name is generally not shown (I think that there is a flag one can change to show those name though.)

• 1. MovieClip is the proper type for a Sprite in an ActionScript.

Equal (typed)

Pop two integers, floats or strings, compute whether they are equal and push the Boolean result back on the stack.

The != operator can be simulated using the Logical Not action right after the Equal (typed).

If a mix set of types is popped from the stack, conventional conversions occur. Strings may be transformed to numbers and numbers to strings as with the untyped Equal operator.

Equal

Pop two values, compare them for equality and put the Boolean result back on the stack.

The != is created by adding a Logical Not after the Equal action.

The way the values are converted is not clearly documented. The fact is that this operation generally transforms the strings into integers or floating points which is not ECMA Script compliant.

This action should only be used in SWF version 4.

Extends

The Extends action will be used to define a new object extending another object. The declaration in ActionScript is:

class A extends B;

In an SWF action script, you don't exactly declare objects, you actually instantiate them and define their functions. This action creates a new object named s₂ which is an extension of the object s₁.

Use this action whenever you need to inherit an object without calling its constructor.

FSCommand2

Execute the external command (s₂) passing on parameters (s₃, s₄ ... s_n.) The external command is likely a JavaScript function.

IMPORTANT NOTES

Ammar Mardawi sent a correction for this action and it looks like it works the way it is described now.

As of version 9, this action is not defined in the official Flash documents. It also does not seem to be functional in a movie. In order to run an FSCommand, use the Get URL2 with a URL that starts with "FSCommand:". For example, in an SSWF script:

action {
   push "FSCommand:hidemenu";
   push "_self";
};
action "url";

This Flash code will call the JavaScript function named:

    <flash script name>_DoFSCommand(command, args);

Where the <flash script name> is the name you give your embed tag (name="my_movie" means my_movie_DoFSCommand() is called.)

For instance, you could generate an alert with the following code:

<script type="text/javascript">
  function my_movie_DoFSCommand(command, args)
  {
     alert(command + " was posted!");
  }
</script>
<embed src="movie_no1.swf" name="my_movie" ... ></embed>

Note that the filename does not need to match the name.

Get Member

Pop one string or an integer (member name), pop an object reference, define the value of that object member and push the result back on the stack.

Objects include some special members such as:

Note that in ActionScript these special members are not written with the underscore character. (i.e. you may find this.parent in a script, and parent will be converted to _parent the SWF movie.)

Get Property

Query the property n₁ of the object named s₂ (a field in a structure if you wish), and push the result on the stack. Note that since version 5, it is preferable to use Get Member or Call Method when a corresponding variable or function member is available on the object.

Get Target

Pop an object, if it is a valid sprite (same as movie or thread), push it's path on the stack.

A sprite path can be used by different other actions such as the Goto Expression.

Get Timer

Get the current movie timer in milliseconds and push it on the stack. The current movie is defined with the Set Target action.

This is equivalent to the number of frames that have been played so far.

This action is similar to Get Property of frames loaded.

Get URL

Load the specified URL in the specified target window.

When the target is set as "_level0", the current SWF file is replaced by the file specified in the f_url field. The name in the f_url field should be a proper SWF file or the area will simply become black.

When the target is set as "_level1", something special is supposed to happen. I still don't know what it is...
Also the effect of _level1 + an empty URL is ... (to remove level1?)

The URL can be a JavaScript command when the protocol is set to "javascript:". For instance, you can call your function as follow: "javascript:MyFunction(5)". If you want to use dynamic values, you will need to concatenate strings as required and use Get URL2 instead.

The target can also be set to the regular HTML names such as "_top" or a frame name.

Get URL2

Pop two strings, the URL (s₂) and the target name (s₁).

All the usual HTML target names seem to be supported (_top, _blank, <frame name>, etc.) You can also use the special internal names _level0 to _level10. _level0 is the current movie. Other levels, I'm still not too sure how these can be used.

Use f_method to tell Flash how to handle the variables (see table below). The variables of the current SWF context can be forwarded to the destination page using GET or POST (this means you can create dynamic forms with full HTML conformance).

It seems that in V4.x (or would it be in V6.x?!? — it doesn't seem to work in V5.x) you could use URL2 to read a text file (with a .txt extension) with a list of variables using something like this:

Push URL "myvars.txt", Target "_level0"; Get URL2;

The syntax of the file myvars.txt is a set of lines defined as a variable name followed by an equal sign and the contents of that variable. If contents of a single variable is more than one line, start the following line(s) with an ampersand to continue that one variable.

The URL can also start with "javascript:" in which case the given browser JavaScript implementation receives the call.

IMPORTANT NOTE

The Get URL2 action is the one used to generate an FSCommand21. Please, visit that other action for more information on how to call a JavaScript function from your Flash animation.

• 1. The FSCommand2 action is not implemented in Flash players. If it is, it does not work for me... If you were able to work it out, send me a sample Flash animation that works with it! Thank you.

Get Variable

Pop one string, search for a variable of that name, and push its value on the stack. This action first checks for local variables in the current function. If there isn't such a variable, or the execution is not in a function, then the corresponding global variable is read.

The variable name can include sprite names separated by slashes and finished by a colon as in. Only global variables are accessible in this way.

Example:

/Sprite1/Sprite2:MyVar

In this example, the variable named MyVaris queried from the sprite named Sprite2which resides in Sprite1.

In a browser you can add variables at the end of the movie URL (as defined in the W3C docs) and these will automatically be accessible via this Get Variable action.

Example:

my_movie?language=jp

Defines the variable language and sets it to "jp".

Since Flash V5.x, there are internal variables available to you and these can be read with the Get Variable action.

Goto Expression

Pop a value or a string and jump to that frame. Numerical frame numbers start at 0 and go up to the number of frames - 1. When a string is specified, it can include a path to a sprite as in:

/Test:55

When f_play is ON (1), it wakes up that sprite (movie, thread). Otherwise, the frame is shown in stop mode (it does not go past the Show Frame tag.) This action can be used to playback a sprite from another given a set of events.

Goto Frame

The playback continues at the specified frame. Frame numbers start at 0 and go up to to total number of frames - 1.

A frame appears at each new Show Frame tag.

For a goto frame with a dynamic frame number, use the Goto Expression action instead.

Goto Label

Go to a named frame. Frames are given names with the use of the FrameLabel tag.

This action has a behavior similar to a Goto Expression with a string.

Greater Than (typed)

Similar to Swap + Less Than. It checks whether the second parameter is greater than the first and return the Boolean result on the stack.

This is the preferred way of applying the Greater Than and Less Than or Equal, i.e. Not(Greater Than), test since version 5.

Implements

This action declares an object as a sub-class of one or more interfaces. The syntax here is simple, the real implementation is quite unbelievably difficult to fathom.

The following shows you how you can add an implements of interfaces "A" and "B" to the class "C". Notice that class "C" needs to already exist. Here we assume that all classes are defined in the global scope.

	push data "_global"
	get variable
	push data "A"
	get member
	push data "_global"
	get variable
	push data "B"
	get member
	push data 2
	push data "_global"
	get variable
	push data "C"
	get member
	implements

This is useful to pass C as if it were of type A or B which some functions may expect. Frankly, in the old ActionScript scheme functions do not declare the type of their parameters, so it does not matter that much.

Increment

Pop one number, add 1 to it and push it back on the stack.

Instance Of

Pop the name of a constructor (s₁ - ie. "Color") then an object (o₂). Checks whether the object is part of the class defined by the named constructor. If so, then true is push on the stack, otherwise false.

Since SWF version 7, it is possible to cast an object to another using the Cast Object action. This action returns a copy of the object or Null, which in many cases can be much more practical.

Integral Part

Pop one value, transform it into an integer, and push the result back on the stack.

The popped value can already be an integer in which case this instruction has no effect.

Other similar features are available in the Math object.

Less Than (typed)

Pop two integers, floats, or strings, compute whether they are ordered from smaller to larger and push the Boolean result back on the stack.

It is possible to test whether two values are Greater Than or Equal using the Logical Not operator on the result of Less Than. The Greater Than (typed) operator is used to support the other two comparison operators (thus eliminating the need to swap the top of the stack as in version 4.)

Less Than

Pop two values, compare them for inequality and put the Boolean result back on the stack.

Other comparison operators:

• Less Than or Equal (n₂ <= n₁)

Swap + Less Than + Logical Not

• Greater Than or Equal (n₂ >= n₁)

Less Than + Logical Not

• Greater Than (n₂ > n₁)

Swap + Less Than

Note that this operator should only be used in version 4. Since version 5, it is better to use Less Than (typed) or Greater Than (typed).

Logical And

Pop two values, compute the Logical AND and put the Boolean result back on the stack.

IMPORTANT NOTE

If b₂ is the result of a function call and b₁ is false, then that function should not be called. With this action, however, b₁ and b₂ are just Boolean values on the stack. So to properly implement a Logical AND in your compiler you want to do something like this:

call f1       // b1 does not need to come from a function call
duplicate
logical not
branch if true, skip
call f2
logical and   // we could also pop just before calling f2
label skip:

Logical Not

Pop one value, compute the Logical NOT and put the result back on the stack.

This operator is often used in combination with the comparison operations to generate the opposite.

Logical Or

Pop two values, compute the Logical OR and put the Boolean result back on the stack.

IMPORTANT NOTE

If b₂ is the result of a function call and b₁ is true, then that function should not be called. This action, however, is just that. It expects two Boolean, b₁ and b₂, on the stack. So to properly implement  the Logical Or in your compiler, you want to test the result of each function call. There is a sample implementation:

call f1       // b1 does not need to come from a function call
duplicate
branch if true, skip
call f2
logical or    // we could also pop just before call f2
label skip:

Modulo

Pop two numbers, compute the modulo and push the result back on the stack.

Note that the operator can compute a floating point modulo (in case at least one of the parameters is a floating point.)

Multiply

Pop two values, multiply them and put the result back on the stack.

New

Pop the class name for the new object to create. Pop the number of arguments. Pop each argument (if i₂ is zero, then no arguments are popped.) Create an object of class s₁. Call the constructor function (which has the same name as the object class: s₁). The result of the constructor is discarded. Push the created object on the stack. The object should then be saved in a variable or object member.

New Method

Pop the name of a method (can be the empty string), pop an object1 (created with the Declare Object,) pop the number of arguments, pop each argument, create a new object, then call the specified method (function s₁ if defined, otherwise function s₂) as the constructor function of the object, push the returned value on the stack. This allows for overloaded constructors as in C++.

• 1. Yes. This contradicts the definition above. I will have to confirm which is correct.

Next Frame

Go to the next frame. This means the next Show Frame tag will be hit. This action does not change the play status.

Number

Pop one item and transform it into a number (integer or floating point.) If a₁ is already a number, it is simply pushed back on the stack.

For strings it works as you would expect (see the strtof(3C) manual pages).

For a user defined object, the method named valueOf() is called. You can declare that function on your own objects to get this action to retrieve the value.

Or

Pop two integers, compute the bitwise OR and push the result back on the stack.

Ord (multi-byte)

Pops one string, compute the multi-byte value of its first character and put it on the stack.

In Flash, multi-byte characters are limited to 16 bits (UCS-2).

Ord

Pop one string, compute the ASCII value of its first character and put it back on the stack.

This function does not take UTF-8 in account. In other words, it can be used to parse a string byte per byte. To get the UTF-8 value of characters, use the Ord (multi-byte) instead.

Play

Enter the standard (default) auto-loop playback. The action only affects the current target.

To stop the playback, use the Stop action.

Pop

Pop one value from the stack and ignore it. This action is often used to simulate a procedure (versus a function.) Whenever you call a function, and the result has to be ignored, the pop action is used.

Previous Frame

Go to the previous frame. This is the opposite of the Next Frame action.

Push Data

struct {
	unsigned char   f_type
	<type>          f_data
} f_push_data[<variable>];

Push some immediate data on the stack. This action was introduced in V4.0. The supported data types vary depending on the version of the player you have. As many values as necessary can be pushed at once. The f_push_data structure will be repeated multiple times as required. For instance, to push two strings on the stack at once, you would use the following code:

96
0C 00
00 't' 'e' 's' 't' 00
00 'm' 'o' 'r' 'e' 00

Most of the time, it is a good idea to push more data and then use the Swap action to reorder. Extra PushData actions require at least 3 bytes when the Swap action is only one.

The following is the table of types accepted in this action:

string	f_string

float	f_float;

unsigned char	f_register;

unsigned char	f_boolean;

unsigned char	f_value[8];

double	result;
char	value[8];

value[4] = ReadByte(input_stream);
value[5] = ReadByte(input_stream);
value[6] = ReadByte(input_stream);
value[7] = ReadByte(input_stream);
value[0] = ReadByte(input_stream);
value[1] = ReadByte(input_stream);
value[2] = ReadByte(input_stream);
value[3] = ReadByte(input_stream);

result = * (double *) value;

unsigned long	f_integer;

unsigned char	f_reference;

unsigned short	f_reference;

Random

Pop one number representing the maximum value (not included) that the random() function can return, push the generated value on the stack. n₁ should not be zero or negative.

Since version 5, you should use the Math.rand() member function instead of this action.

Remove Sprite

Pop the string s₁ representing the name of the sprite (movie, thread) to be removed from your display list.

It is not possible to remove the root movie with this action. To do so, you want to load another movie with the Get URL or Get URL2 actions.

Return

Pop one object and return it to the caller. The result is stacked on the caller's stack, not the stack of the function returning.

Note that up to version 8, your functions could push multiple entries and return all of them to the caller. Since it is not compatible anymore (and it was never supposed to work that way,) it is strongly suggested that you avoid that practice. Instead use a Declare Array action.

Set Local Variable

Pop a value and a local variable name. Create or set a local variable of that name with the (initial) value as specified. The same local variable can safely be set in this way multiple times. To only declare a local variable (i.e. no default value to initialize the variable,) use the Declare Local Variable instead.

Note that the Get Variable action automatically gets a local variable if it exists. In order to still access a global variable, use the path syntax as in "/my_var".

Instead of local variables, it is also possible to use registers. There are 4 in Flash versions 4 through 6. Since version 7, you have access to 254 registers in Declare Function (V7). Remember, however, that if you tell users that they can always access a variable by name, then they could dynamically generate the name in which case changing such a variable into a register will break their code.

Set Member

Pop a value a₁ representing the new member value.

Pop one string or integer a₂ representing the name of the member to modified or create.

Finally, pop an object reference o₃.

If the member a₂ doesn't exists yet, create it.

Finally, sets the object member a₂ to the value a₁.

To read the value of a member see the Get Member action.

Set Property

Pop a value from the stack representing the new property value.

Pop the name of the property to be changed. Note that the property scheme is from version 4 and as such the property name can be represented by a number. Older version actually only accepted floating point numbers.

Finally, pop the name of the object where the specified field property is modified.

Set Target (dynamic)

Pop one string from the stack. If the string is the empty string, then the next actions apply to the main movie. Otherwise it is the name of a Sprite1 and the followings actions apply to that Sprite only. (Note that some actions, like the Set Target action, are always used globally.)

This was the old mechanism used to apply actions to a given Sprite. Since version 5, it is preferable to see Sprites as objects and manipulate them using method calls and variables (see Call Method and Get Member actions.)

• 1. Note that the name of a sprite is specified in the PlaceObject2 tag so as to be able to include the same DefineSprite tag multiple times and still be able to distinguish each instance.

Set Target

If the string f_target is the empty string, then the next actions apply to the main movie.

Otherwise it is the name of a Sprite and the followings actions apply to that Sprite only.

In order to use a dynamic name for the target, use Set Target (dynamic) instead.

Note that this action should not be used since SWF version 5 where you can instead access the movie members (i.e. view Sprites as objects with data members and functions.) For instance, to call the play() function on a Sprite, one can use this code:

  push data 0;
  push data "this";
  get variable;
  push data "_parent";
  get member;
  push data "play";
  call method;

This is equivalent to: this._parent.play(), or a Set Target of the parent object and a Play action.

Set Variable

Pop one value and one string, set the variable of that name with that value.

If this instruction is executed inside a function and a local variable of that name exists, then that local variable value is changed (as long as the name is not a full path name.) Note that to make sure that you set a local variable, it is a good idea to use the Set Local Variable action instead.

Nothing is pushed back on the stack. Variable names can be full paths as defined in the Get Variable action.

Shift Left

Pop two integers, shift the 2^nd one by the number of bits specified by the first integer and push the result back on the stack.

The second integer will be masked and only the number of bits considered useful will be used to do the shift (most certainly 5 or 6 bits.)

This action ignores the sign of the number being shifted (it gets lost.)

Shift Right

Pop two integers, shift the 2^nd signed integer by the number of bits specified by the first integer and push the result back on the stack.

To right shift an unsigned integer, use Shift Right Unsigned instead.

This action repeats the sign bit of the integer being shifted. This means negative numbers remain negative and positive numbers remain positive.

Shift Right Unsigned

Pop two integers, shift the 2^nd unsigned integer by the number of bits specified by the first integer and push the result back on the stack.

To shift a signed integer to the right, use the Shift Right action instead.

This action will transform all the input numbers to positive numbers (as long as the shift is at least 1.)

Start Drag

Pop a target (sprite, movie, thread) name s₁.

Pop a first Boolean b₂, which, when true, means that the mouse pointer is locked to the center of the object being dragged.

Pop a second Boolean b3, which when true means that the mouse pointer is constrained to the specified rectangle1 (n₄ to n₇, representing y₂, x₂, y₁, x₁.)

Once this function was called, the object attached to the mouse pointer will follow the mouse until a Stop Drag action is applied or another object is defined as the object being dragged with another Start Drag.

• 1. The rectangle is not defined when b₃ is false.

Stop

Stop playing the current target (remain on the same Show Frame.)

Only a button, another script, or the plugin menu can be used to restart the movie.

Stop Drag

Stop the current drag operation. If this action is run when no drag operation is in effect, it has no effect.

To start a drag operation, use the Start Drag action.

Stop Sound

This action is a global action that stops all sound effects at once.

Store Register

Pop one value from the stack, push it back on the stack and also store it in one of 4 or 256 registers which number is specified in the tag (0, 1, 2 or 3 only if not in a Declare Function (V7). I tried other numbers and they don't work in SWF version 6 or older.) Until set a register has the value undefined. The value of a register can be retrieved with a Push Data action and the register type with the matching register number.

(To be tested) It is likely that trying to read a register which is not legal in a Declare Function (V7) will generate an exception (Yes! A Throw!) but I wouldn't be surprised if you just get undefined.

Strict Equal

Pops two values and return whether they are strictly equal. No cast is applied to either s1 or s2. Thus two items of different type are not equal (0 == "0" is true, but 0 === "0" is false.)

Strict Mode

Set the strict mode (f_strict != 0) or reset the strict mode (f_strict == 0).

The strict mode is used with arithmetic and comparison operators and some other such ActionScript features.

String

Pops one item and transform it into a string.

For strings, this action has no effect.

For numbers, it works as expected, it transforms them in a string (see the sprintf(3C) manual pages).

For a user defined object, the method named toString() is called.

This is similar to a Cast Object operation, although it is available in version 5 and obviously it only works for strings. It is most certainly preferable to use a Cast Object operation since version 7.

String Equal

Pops two strings, compute the equality and put the Boolean result back on the stack.

IMPORTANT

The true meaning of this operator was to apply the String cast to both values, then compare the result as strings. This is not really good JavaScript as per ECMA, so later Macromedia added the strict comparison operators instead. This is why this action should only be used in a Version 4 of SWF. Newer versions should use Strict Equal or plain Equal.

String Greater Than

Similar to Swap + String Less Than although not exactly the same.

It checks whether the second string is greater than the first and return the Boolean result on the stack.1

IMPORTANT

The true meaning of this operator was to apply the String cast to both values, then compare the values as strings. This is not really good JavaScript as per ECMA, so later Macromedia added the strict comparison operators instead. This is why this action should never be used. Instead, one should use Greater Than (typed) and the Cast Object operator as required.

• 1. I'm not too sure why Macromedia introduced this action in SWF version 6.

String Length (multi-byte)

Pop one multi-byte string, push its length in actual character on the stack.

This action works as expected with plain ASCII and international UTF-8 strings.

String Length

Pops one string and push its length in bytes on the stack.

This instruction can be used to get the size of a binary buffer represented by a string. For a real string with characters, it is preferable to use the String Length (multi-byte) instruction instead.

IMPORTANT NOTE

This action will not return the proper number of characters if the input string includes multi-byte UTF-8 characters.

String Less Than

Pop two strings, compare them, push the Boolean result back on the stack.

This operation was available since version 4 of SWF. Since Macromedia introduced String Greater Than (typed) in version 6, it is likely that this operator is expected to legally be used, although it seems to me that the Less Than (typed) action should be used instead.

SubString (multi-byte)

Pop a multi-byte string s₃, get i₁ characters from the position i₂ (1 based) and push the result back on the stack.

The start position is given in characters. This action works properly with international characters.

i₁ is expected to be positive or zero.

Since version 5, the String object substr(), substring() or slice() functions should be used instead.

SubString

Pop two values and one string, the first value is the new string size (at most that many characters) and the second value is the index (1 based) of the first character to start the copy from. The resulting string is pushed back on the stack.

Since version 5, the String object substr(), substring() or slice() functions should be used instead.

IMPORTANT NOTE

This action acts on bytes, not UTF-8 characters. In other words, it does not work with international text. For that purpose use the SubString (multi-byte) action instead.

Subtract

This action pops two values, subtract the first one from the second and put the result back on the stack.

Swap

Pop two items and push them back the other way around.

This action is very useful when you just called a function and need to swap that parameter with the previous function call when all you should have to do is call.

Throw

This action pops one item from the stack and returns its value as the exception parameter. You can catch exceptions using the Try action.

Toggle Quality

Change the quality level from low to high and vice versa. At this time, not sure what happens if you use medium!

Note that the quality is defined on the root only and affects the entire output.

Newer SWF versions (since version 5) should use the movie quality variable member instead of this direct action.

Trace

Print out string s₁ in the debugger output window. Ignored otherwise.

Note that action can considerably slow down your animation. You should only use is sporadically and remove it from final animations.

Try

Declare a try/catch/finally block.

This has the behavior of the action script:

	try { ... }
	catch(name) { ... }
	finally { ... }

In version 7, there are no definition of exceptions in the ActionScript interpreter. However, you can write functions that Throw.

The semantic of the try/catch/finally block is very well defined in ECMA 262 version 3 (see pages 87/88).

f_finally and f_catch may not both be zero or the semantic of the try block would be invalid. f_try_size, f_catch_size and f_finally_size are defined in bytes and give the size of each of the block of instructions just like a function definition.

IMPORTANT
Do not terminate these blocks with an End action

When f_catch_in_register is set to 1, a register number is specified instead of a variable name. This will usually be faster. Note that the variable name or register number should not overwrite another variable or register to be fully compliant.

Note that the stack is used only if the a function throws an exception and it is used internally (whether or not you defined a catch). So this is why it is marked as n.a. since from before or after the statements, the stack will be the same.

Type Of

Pop one item from the stack, define its type and push the name of its type back on the stack.

The existing types are as follow:

number
boolean
string
object
movieclip
null
undefined
function

Note that this action does not distinguish between different user objects. All of them are object.

Wait For Frame (dynamic)

Pop a value or a string used as the frame number or name to wait for. The frame can be specified as with the Goto Expression. If the frame was not reached yet, skip the following f_skip actions.

WARNING

The f_skip parameter is defined as a byte meaning that you can only skip a small number of actions (255 bytes). In order to skip more actions, use the Branch Always action as required.

Wait For Frame

Wait until the frame specified in f_frame is fully loaded to execute actions right after this one. Otherwise skip the specified number of actions. This is most often used with a Goto Frame like in:

Next Frame
Wait for Frame #10
  (otherwise skip 1 action)
Goto Frame #5
Play
End

This will usually be used to display some

Loading...

info before the complete movie is loaded.

With

The variable references within the following f_size bytes of action are taken as names of members of the specified object o₁. When no member of that name is available in that object, the previous With, or the corresponding global variable is queried. This is similar to the Pascal language with instruction or to the Set Target (dynamic) for movies.

Note that the number of With within other With is limited to 7 in version 5 and 15 since version 6 (note that the official documentation says 8 and 16, but it seems that is wrong.) Additional With blocks are simply ignored. The size defines up to where the With has an effect (the f_size is taken as a branch offset except that it is always positive).

Note that it is to the creator of the action scripts to ensure the proper nesting of each With.

XOr

Pop two integers, compute the bitwise XOR and push the result back on the stack.

This operator is used to generate a bitwise NOT with an immediate value of -1. (There is not bitwise NOT action.)

SWF Internal Functions

Since Flash version 5, you can use internal functions (really member functions or methods of internal objects.) These functions are always available. These methods are called using the Call Function action with the name of the object and function separated by a period. A few of these internal functions are duplicates of some direct action script instructions. In general, it is preferred to use these internal functions rather than the direct action. However, direct actions are a good way to optimize your ActionScript code.

Similarly, you can access internal constants (really variable members of internal objects such as the number π.) These constants are always available. These variable members are read using the Get Variable action with the name of the object and variable separated by a period. This can increase the precision of some values such a π and e and give you information about the system on which the plug-in is currently running. These variable members are usually read-only.

The name of the objects and their functions are case insensitive. Thus "Math.SIN"is equivalent to "math.sin".

Sample to compute the sine of an angle given in degree:

	// expect the angle on the top of the stack here
	Push Data (string) "math.pi"
	Get Variable
	Multiply
	Push Data (float) 180.0
	Swap
	Divide
	Push Data (integer) 1
		  (string) "math.sin"
	Call Function
	// the result is on the top of the stack
	// i.e.:  math.sin(<input> * math.pi / 180.0);

Since Version 8, Macromedia created a new website called livedocs that includes a complete and up to date documentation of the scripting language (ActionScript) and the default objects coming with Flash players. To some extend, it is otherwise possible to enumerate most of the objects available with the Enumerate Object action.

Sprite Properties

The following is the list of currently accepted properties or fields for the Get Property and the Set Property actions. Note that the properties can be specified with either an integer (type 7, requires V5.0+) or a single precision floating point (type 1, V4.0 compatible). And since strings are automatically transformed in a value when required, one can use a string to represent the property number (type 0). It works with a double value, I even tested a Boolean and null and it works. Obviously it isn't a good idea to use these. The default should be a single precision float. Please, see the Push Data action for more information about data types.