Expression Class Reference Manual


BACK TO README.htm

Here's a list of all the methods, properties and events contained in the Expression class. The Expression class allows the programmer to control several animated parts of a character at the same time.

The character has a list of states. Each state defines how the parts of the character should behave. A state can be viewed as a specific pose or expression of the character.

The character can have up to two states at once: The default state and the reaction state. A reaction state is a state that happens temporarily and will automatically return to the default state when the time is up.

Character reactions can be made to trigger automatically by connecting them to events. A character can also be made to react to checkpoint events of an Expansion object

Note: The words "character" and "Expression object" are used interchangeably in this reference manual


Index

Methods
Expression Constructor
activate Starts or stops the flow of time for the character.
addPart Adds a new MovieClip as a part of the character.
getPartID Returns the ID number of the MovieClip given in the parameter.
removePart Removes a MovieClip from the character.
removePartAt Removes a MovieClip from the character.
getPartAt Returns the MovieClip of the character given by the ID number.
addState Adds a state Array to the character with a unique name.
removeState Given the name of a state, the state is removed from the character.
getStateByName Returns the state Array associated with the name given in the parameter.
setState Sets the character's state to the state given by the name in the parameter.
getBaseValues Given the ID of a MovieClip, returns a list of the values it had when it was inserted using the addPart method.
addStateAttributes Adds attributes to a state Array.
addPartToState Adds the attributes of a specific part to a state Array.
react Saves the character's current state, switches to the stage given by the parameter, then returns back to the old state.
endReact If a character is reacting, returns back to the default state.
addReaction Define's a character's reaction to a specific event.
getReaction Returns the and object representing the reaction a character will have to a specific event.
removeReaction Stops a character from reacting to a certain event.
reactTo Allows the character to react to the checkpoint events of an Expansion object.
destroy Call this function to unlink event handlers associated with the Expression object.
Properties
FRAME Array position of the frame attribute for each "part" object of a state Array.
ROTATION Array position of the rotation attribute for each "part" object of a state Array.
ROTATION_SPEED Array position of the rotation speed attribute for each "part" object of a state Array.
X_POS Array position of the x attribute for each "part" object of a state Array.
Y_POS Array position of the y attribute for each "part" object of a state Array.
ANIMATED Constant representing the "animated" type of part.
MOVABLE Constant representing the "movable" type of part.
state The name of the state the character is currently in.
curState A copy of the state Array of the state the character is currently in.
defaultState The name of the default state of the character.
offset The scale of the sine wave representing the character's breathing position.
frequency The frequency of the sine wave representing the character's breathing position.
angle The angle of the sine wave representing the character's breathing position.
position The current value of the sine wave representing the character's breathing position.
canBlink Indicates whether the character can blink or not.
blinking Indicates whether the character is blinking or not.
timer Indicates how many frames are left for a character's reaction to end.
reacting Indicates whether the character is reacting or if the character is in its default state.
interruptible Indicates whether the character can react while reacting or not.
Events
"blink" The character has started blinking.
"endblink" The character has finished blinking.
"enterFrame" The character has just completed its actions for one frame.
"react" Just started reacting.
"endreact" The character just finished reacting.

Methods


Expression()

public function Expression(s:Stage)

Creates a new Expression object. The Expression object controls several parts of the character to represent expressions or poses.

Parameters

stage:Stage A reference to the stage. Used for enterFrame event handling.

activate()

public function activate(b:Boolean=true)

Starts or stops the flow of time for the character.

Parameters

b:Boolean A boolean value indicated whether to start or stop the enterFrame handler of the Expression object.

addPart()

public function addPart(mc:MovieClip,type:int=ANIMATED,eye:Boolean=false):int

Adds a MovieClip as a part of the character.

Parameters

mc:MovieClip The MovieClip representing the part to add to the character.
type:int The animation type of the MovieClip being added. The value can be Expression.ANIMATED or Expression.MOVABLE. An part of type ANIMATED will jump between frame loops when the character's state changes. A part of type MOVABLE will pass through a transition animation to get to the destination frame loop.
eye:Boolean Indicates whether this part is an eye or not. An eye is a MovieClip that will ocasionally jump to a frame loop labeled "blink", then return back to its default frame loop. This will never happen while the character is reacting or if the canBlink attribute is set to false

Returns

The ID number of the part inserted into the character. This Id number can be used to reference the object in other functions of the class.


getPartID()

public function getPartID(part:MovieClip):int

Returns the ID number of the MovieClip given by the parameter. If the MovieClip does not exist in the Expression object, this function returns -1.

Parameters

part:MovieClip A reference to the MovieClip associated with a part of the character.

Returns

The ID number of the MovieClip given in the first parameter.


removePart()

public function removePart(mc:MovieClip)

Removes the MovieClip from the Expression object. If the MovieClip does not exist in the Expression object, nothing happens.

Parameters

mc:MovieClip The MovieClip to be removed from the character.

removePartAt()

public function removePartAt(n:uint)

Removes the part of the character given by the ID number in the first parameter. If the character does not have a part with this ID number, nothing happens.

Parameters

n:uint The ID number of the part to be removed.

getPartAt()

public function getPartAt(n:int):MovieClip

Returns the MovieClip associated with the part of the character given by the ID number in the first parameter.

Parameters

n:int The ID number of the part to be returned.

Returns

The MovieClip of the part given by the ID number.


addState()

public function addState(nam:String, s:Array)

Adds a new state Array to the list of states the character has. The state is identified by a name, given as a String by the first parameter of the function.

Parameters

nam:String The name of the state to be stored in the Expression object.
s:Array An Array representing the state to be inserted.

Notes

Note: The state stored in the Expression object is a copy of the state given by the parameter. To change a state after having inserted it into the Expression object, try calling getStateByName() to get a reference to the inserted state.

Note: It is recommended to create states only after having inserted all of the parts of the character

The state Array

The state Array has three properties: canBlink, frequency and offset. Each element of the state Array represents the properties of the part with the ID number of the specific element. The content of each element is an Array of length 5, where each of its elements represents a property of the part to be modified by the state: FRAME, ROTATION, ROTATION_SPEED, X_POS and Y_POS.

This diagram is a visual representation of the state Array


removeState()

public function removeState(nam:String)

Removes the state given by the name in the first parameter. If the character does not have a state with this name, nothing happens.

Parameters

nam:String The name of the state to remove.

getStateByName()

public function getStateByName(nam:String):Object

Returns a reference to the state Array associated with the name given by the first parameter. This can be used to edit a state that was already inserted into the Expression object. See The state Array to learn about the structure of a state Array.

Parameters

nam:String The name of the state to be returned.

Returns

A reference to the state Array of the state given by the first parameter.


setState()

public function setState(str:String)

Updates the character's default state to the state given by the name in the first parameter. All the values of the character are updated when the function is called. This function will have no effect if:

Parameters

str:String The name of the state to change to.

getBaseValues()

public function getBaseValues(n:uint):Object

Returns an object with the base values of the part with the ID number given in the first parameter. The base values of a part are the values the part had the moment it was inserted into the Expression object. These values are considered the default state of the part. If the part does not exist, this function returns null.

Parameters

n:uint The ID number of the part of which to get the base values.

Returns

An object containing the base values of the part given by the first parameter. The object returned contains the following properties:

x:Number The base X position of the part.
y:Number The base Y position of the part.
scaleX:Number The base horizontal scale of the part.
scaleY:Number The base vertical scale of the part.
rotation:Number The base rotation of the part.

About base values

The base values are used when calculating the destination X, Y and Rotation values for the part in a given state.The destination x, y and rotation for each part of a character is calculated like this:

//For each part
destination[i].x = state[i][X_POS] + baseValue[i].x;
destination[i].y = state[i][Y_POS] + baseValue[i].y;
destination[i].rotation = state[i][ROTATION] + baseValue[i].rotation;

addStateAttributes()

public function addStateAttributes(s:Array,canBlink0:Boolean,freq:Number=NaN,off:Number=NaN)

Writes the canBlink, frequency and offset values into the state Array given by the first parameter. Learn more about these properties by looking at their corresponding attributes in the class definition.

Parameters

s:Array A reference to the state Array to edit. See The state Array to learn about the structure of a state Array.
canBlink:Boolean A Boolean value indicating whether the character can blink in this state or not.
freq:Number The frequency of the sine wave that represents the breathing of the character. By giving NaN as a parameter, the character's frequency property will not change when the character switches to this state.
off:Number The scale of the sine wave that represents the breathing of the character. By giving NaN as a parameter, the character's offset property will not change when the character switches to this state.

addPartToState()

public function addPartToState(s:Array, id:int, frame:String, spin:Number=0.0, speed:Number=1.0, xPos:Number=0.0, yPos:Number=0.0)

Adds the attributes of one of the character's parts to the state Array given in the first parameter.

Parameters

s:Array A reference to the state Array to edit. See The state Array to learn about the structure of a state Array.
id:int The ID number of the part to edit when the character switches to this state. If the character does not contain a part with this ID number, the function will throw an error
frame:String The name of the frame loop the part should go to when the character switches to this state.
spin:Number The rotation the part should have (relative to its base rotation) when the character switches to this state.
speed:Number The number of degrees the part should move in each frame to reach its destination rotation.
xPos:Number The x position the part should have (relative to its base x position) when the character switches to this state.
yPos:Number The y position the part should have (relative to its base y position) when the character switches to this state.

react()

public function react(str:String, t:int=30)

Saves the character's current state, then switches to the state given by the name in the first parameter. The second parameter indicates how many frames the character will remain in the new state. When the time is up, the character will return back to the saved state.

If there is no state with the name given by the first parameter, this function has no effect. If this function is called while the character is still reacting, the old reaction is replaced with the new reaction, but the stored state remains the same as before.

While a character is reacting, the setState() function will not work. Also, the character's "eye" parts will not blink, even if the canBlink attribute is true

Parameters

str:String The name of the state to switch to.
t:int The number of frames to wait before the reaction ends. If this value is less than 0, the reaction will continue indefinitely. call endReact() to manually end the reaction.

endReact()

public function endReact()

If the character is reacting, this function manually ends the reaction. If not, this function has no effects.


addReaction()

public function addReaction(hit:EventDispatcher,type:String,state0:String,timer0:int=30)

This function makes the character react to a specific event given by the first to parameters. The reaction is given by the secon two parameters. This function is equivalent to writing the following code:

hit.addeventListener(type,fn);
function fn(E:Event){
   character.react(state0,timer0);
}

See react() for more information on character reactions.

Parameters

hit:EventDispatcher The object being listened to for an event.
type:String The type of event being listened to.
state0:String The state to go to when the event is triggered.
timer0:int The number of frames the character should spend reacting.

getReaction()

public function getReaction(hit:EventDispatcher,type:String):Object

Returns an object representing the reaction the character will have when the event given by type is triggered in the object given by hit. The object returned contains the following properties:

hit:EventDispatcher The object being listened to for the event.
type:String The type of event to listen for.
state:String The state the character should switch to when reacting to the event.
timer:int The number of frames the character should spend reacting to the event.

Parameters

hit:EventDispatcher The object being listened to for the event.
type:String The type of event to listen for.

removeReaction()

public function removeReaction(hit:EventDispatcher,type:String)

Removes the reaction the character will have to the event given by the second parameter triggered by the object given by the first parameter. If there is no reaction programmed for this event nothing will happen.

Parameters

hit:EventDispatcher The object that will trigger the event being listened for.
type:String The type of event being listened for.

reactTo()

public function reactTo(exp:Expansion,permanent:Boolean=false)

Causes the Expression object to listen to checkpoint events triggered by an Expansion object. See the checkpoint event for more details on Expansion checkpoints. Each time the Expansion object triggers a checkpoint event, the Expression object uses the reaction property of the ReactionEvent object to set the state of the character, and the timer property to set the number of frames the character spends reacting.

If the second parameter is true, the character will switch its default state when the checkpoint event is received. If the second parameter is false, the character will call the react() function instead.

Parameters

exp:Expansion The Expansion object to listen to.
permanent:Boolean If this value is true, the default state of the character changes when a checkpoint event is received. Otherwise, the checkpoint even will call the react() function instead.

Notes

Note: If the ReactionEvent object contains an empty ("") or null String value in the reaction property, it will be ignored by the Expansion object. You can use this to create checkpoints that are not designed to change the character's state.


destroy()

public function destroy()

Always remember to call this function before deleting the Expression object. This function removes all of the events the Expression object is listening for. Failing to call this function may result in a meory leak if the addReaction() or reactTo() function have been used


Properties


FRAME

public static const FRAME:int = 0

The position of the frame loop label attribute in a part of a state Array. For example:

var character:Expression;
//Assume the character already has a set of states
var state:Object = character.getStateByName("state1");

//Two equivalent instructions:
state[0][Expression.FRAME] = "frameloop1";
state[0][0] = "frameloop1";

To learn more about state Arrays, see The state Array.


ROTATION

public static const ROTATION:int = 1

The position of the rotation attribute in a part of a state Array. For example:

var character:Expression;
//Assume the character already has a set of states
var state:Object = character.getStateByName("state1");

//Two equivalent instructions:
state[0][Expression.ROTATION] = 30.0;
state[0][1] = 30.0;

To learn more about state Arrays, see The state Array.


ROTATION_SPEED

public static const ROTATION_SPEED:int = 2

The position of the rotation speed attribute in a part of a state Array. For example:

var character:Expression;
//Assume the character already has a set of states
var state:Object = character.getStateByName("state1");

//Two equivalent instructions:
state[0][Expression.ROTATION_SPEED] = 1;
state[0][2] = 1;

To learn more about state Arrays, see The state Array.


X_POS

public static const X_POS:int = 3

The position of the x attribute in a part of a state Array. For example:

var character:Expression;
//Assume the character already has a set of states
var state:Object = character.getStateByName("state1");

//Two equivalent instructions:
state[0][Expression.X_POS] = 20;
state[0][3] = 20;

To learn more about state Arrays, see The state Array.


Y_POS

public static const Y_POS:int = 4

The position of the y attribute in a part of a state Array. For example:

var character:Expression;
//Assume the character already has a set of states
var state:Object = character.getStateByName("state1");

//Two equivalent instructions:
state[0][Expression.Y_POS] = 0;
state[0][3] = 0;

To learn more about state Arrays, see The state Array.


ANIMATED

public static const ANIMATED:int = 0

An integer value representing the "animated" type of part. Used when calling the addPart() function. An animated part is a MovieClip containig a set of frame loops.

Each frame loop contains a frame at the beginning with a label indicating the name of the frame loop. At the end of the frame loop is usually a frame containing the code this.gotoAndPlay(this.currentLabel);.

Read the Expression tutorial page to learn more about how to configure the frames of an "animated" type of MovieClip


MOVABLE

public static const MOVABLE:int = 1

An integer value representing the "movable" type of part. Used when calling the addPart() function. A movable part is a MovieClip containig a set of frame loops and a set of "transition animations" that are used to transition between the frame loops when the character changes states.

Each frame loop contains a frame at the beginning with a label indicating the name of the frame loop. At the end of the frame loop is usually a frame containing the code this.gotoAndPlay(this.currentLabel);.

For each possible pair of frame loops, there are two transition animations used to connect the two: One to transition from loop 1 to loop 2 and another to transition from loop 2 to loop 1.

At the beginning of each transition animation is a frame with the label "<loop1>2<loop2>", where "loop1" and "loop2" are the labels of. At the ending of each transition animation there is a frame containing the code this.gotoAndPlay("<loop2>");.

Read the Expression tutorial page to learn more about how to configure the frames of a "movable" type of MovieClip.


state

public function get state():String

A read-only variable that indicates the name of the current state the character is in. This value does not always represent the character's default state. It could also be referring to the character's reaction.


curState

public function get curState():Array

A read-only variable that returns a copy of the state the character is currently in. Note that the returned value is only a copy and not a reference to the actual state Array. To get the current state Array, use this code:

//Assume the object exists and is already initialized
var character:Expression;
var state:Object = character.getStateByName(character.state);

defaultState

public function get defaultState():String

A read-only variable. If the character is reaction, this variable contains the name of the state the character will go back to when the character finished reacting. If the character is not reacting, this property returns the same value as the state property.


offset

public function get offset():Number
public function set offset(n:Number)

The scale of the sine wave that represents the character's breathing pattern. This value controls how heavily the character is breathing. Here's an example of how it could be used:

//Assume the Expression object exists and is already initialized
var character:Expression;

//Suppose you have a MovieClip named chest.
//This MovieClip represents the chest of a character.
//At frame 1, the chest is at a normal size
//At frame 30, the chest is at its maximum size.
var chest:MovieClip;

stage.addEventListener("enterFrame",frame);

function frame(E:Event){
   var position:Number = character.position*0.5+0.5;

   //Use the offset value to control
   //how deeply the character is breathing.
   var toScale:Number = position*character.offset*30;


   var chestFrame:Number = 1+Math.floor(toScale);

   //Animate a breathing chest
   chest.gotoAndStop(chestFrame);
}

frequency

public function get frequency():Number
public function set frequency(n:Number)

The frequency of the sine wave that represents the character's breathing process. This value measures how many radians are added to the current breathing angle in each frame. For example: If the frame rate is 20 and you want the character to complete a breathing cycle in one second, you would use this value for the frequency:

character.frequency = Math.PI*2.0/20.0;

angle

public function get angle():Number

A read-only value. The current angle used in the sine function that represents the character's breathing. In every frame, the angle increases its value using the character's frequency property, like this:

//Once per frame
angle = angle + frequency;

The current breathing position is calculated like this:

position = Math.sin(angle);

position

public function get position():Number

A read-only value. The current position of the character's breathing cycle. This value ranges between -1 and 1, and is calculated like this:

position = Math.sin(angle);

This value can be used in conjunction with the offset attribute to animate a character's chest as the character breathes, as seen in this example:

//Assume the Expression object exists and is already initialized
var character:Expression;

//Suppose you have a MovieClip named chest.
//This MovieClip represents the chest of a character.
//At frame 1, the chest is at a normal size
//At frame 30, the chest is at its maximum size.
var chest:MovieClip;

stage.addEventListener("enterFrame",frame);

function frame(E:Event){

   //Switch from the [-1,1] range to the [0,1] range
   var position:Number = character.position*0.5+0.5;

   //Use the offset value to control
   //how deeply the character is breathing.
   var toScale:Number = position*character.offset*30;

   var chestFrame:Number = 1+Math.floor(toScale);

   //Animate a breathing chest
   chest.gotoAndStop(chestFrame);
}

canBlink

public function get canBlink():Boolean
public function set canBlink(n:Boolean)

Controls whether a character can blink or not. If canBlink is set to true, the character has a 1/100 chance of blinking in each frame. When this happens, all of the parts that were defined as an "eye" in the addPart() function will go to a frame loop labeled "blink".

If a character is reacting, changing this value will not allow the character to blink.

To learn more about blinking, see the Expression tutorial page.


blinking

public function get blinking():Boolean

A read-only value. Determines whether the character is blinking or not. You can use the "blink" and "endblink"events to avoid having to test for blinking in every frame.


timer

public function get timer():int

A read-only value. The timer variable tells how many frames are left before the character finishes reacting. If the character is not reacting, this variable will have the value -1. The value -1 could also indicate that the character is reacting indefinitely.


reacting

public function get reacting():Boolean

A read-only value. This variable determines if a character is reacting or not.


interruptible

public function get interruptible():Boolean
public function set interruptible(n:Boolean)

This value indicates whether the character can override the current reaction with a new one. The default value is true. If this value is false, the react() will have no effect while the character is reacting.


Events


"blink"

"blink"

This event fires when a character blinks. It is possible for a character to blink more than once before an "endblink", causing the two blinking actions to overlap. However, the "endblink" event guarantees that a character is no longer blinking when it is fired.

To learn more about blinking, see the Expression tutorial page.


"endblink"

"endblink"

This event fires when one of the character's eye parts reaches the "endblink" frame in its blinking animation.

To learn more about blinking, see the Expression tutorial page.


"enterFrame"

"enterFrame"

This event fires after the Expression object has completed its own "enterFrame" event handler. You can use this to make sure your code always runs after the Expression object has updated


"react"

"react"

This event fires when the react() function is called and the character successfully reacts. This can be used to detect when the character reacted to an event without having to listen to that event.


"endreact"

"endreact"

This event fires when the character, while reacting, finishes the reaction.


BACK TO README.htm

© 2014 Doom the wolf. http://doom-the-wolf.deviantart.com