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
| 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. |
public function Expression(s:Stage)
Creates a new Expression object. The Expression object controls several parts of the character to represent expressions or poses.
| stage:Stage | A reference to the stage. Used for enterFrame event handling. |
public function activate(b:Boolean=true)
Starts or stops the flow of time for the character.
| b:Boolean | A boolean value indicated whether to start or stop the enterFrame handler of the Expression object. |
public function addPart(mc:MovieClip,type:int=ANIMATED,eye:Boolean=false):int
Adds a MovieClip as a part of the character.
| 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 |
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.
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.
| part:MovieClip | A reference to the MovieClip associated with a part of the character. |
The ID number of the MovieClip given in the first parameter.
public function removePart(mc:MovieClip)
Removes the MovieClip from the Expression object. If the MovieClip does not exist in the Expression object, nothing happens.
| mc:MovieClip | The MovieClip to be removed from the character. |
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.
| n:uint | The ID number of the part to be removed. |
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.
| n:int | The ID number of the part to be returned. |
The MovieClip of the part given by the ID number.
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.
| nam:String | The name of the state to be stored in the Expression object. |
| s:Array | An Array representing the state to be inserted. |
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 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
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.
| nam:String | The name of the state to remove. |
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.
| nam:String | The name of the state to be returned. |
A reference to the state Array of the state given by the first parameter.
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:
| str:String | The name of the state to change to. |
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.
| n:uint | The ID number of the part of which to get the base values. |
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. |
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;
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.
| 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. |
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.
| 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. |
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
| 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. |
public function endReact()
If the character is reacting, this function manually ends the reaction. If not, this function has no effects.
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.
| 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. |
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. |
| hit:EventDispatcher | The object being listened to for the event. |
| type:String | The type of event to listen for. |
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.
| hit:EventDispatcher | The object that will trigger the event being listened for. |
| type:String | The type of event being listened for. |
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.
| 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. |
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.
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
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.
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.
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.
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.
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.
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
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.
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.
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);
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.
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);
}
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;
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);
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);
}
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.
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.
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.
public function get reacting():Boolean
A read-only value. This variable determines if a character is reacting or not.
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.
"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"
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"
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"
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"
This event fires when the character, while reacting, finishes the reaction.
© 2014 Doom the wolf. http://doom-the-wolf.deviantart.com