Advanced avatar (Flash tutorial)

If you have never created an avatar for Whirled, you probably want to look into our Simple avatar (Flash tutorial). If you feel sufficiently experienced, feel free to move forward with the more advanced steps below. After becoming familiar with this tutorial, move on to the Remixable avatar (Flash tutorial).

Basic Settings
You can configure your basic document properties under Modify &rarr; Document....
 * Dimensions: An avatar may be any size under the maximum of 600(wide)x450(tall) pixels.
 * Frame rate: All Whirled avatars must be 30 frames per second.
 * Background color: You can use any background color you like, but it won't appear in Whirled.

Avatar Scenes
An avatar's actions and states are all controlled by scenes and the names you give them. There's no code involved - just use the right naming convention, and Whirled will automatically incorporate your scenes into the avatar's menu of options. Look at the examples in each category to see how scene naming defines what a scene does.
 * All scenes should depict the avatar facing left. Whirled will handle flipping the avatar if it faces the other way.
 * All scenes run exactly their frame duration. If you're bringing over an avatar from the old method, you'll have to either break your movieclips out into the scene, or just make your scenes as long as the movieclips they hold.

States
States are avatar behaviors that persist until you change them. If you walk or play an action, the avatar will return to the selected state. If someone else enters the room, she will see your avatar in the same state that you see.
 * State names are case-sensitive and must be capitalized.
 * States automatically loop.

Some example states:
 * state_Default
 * state_Dancing
 * state_Sitting
 * state_Fighting

Walking
Walking scenes are triggered whenever your avatar traverses space in the room. Walking scenes can be associated with specific states, in order to have unique walks for various states. If you have a state with no associated walk, Whirled will just move your avatar without the walk.

Some example walks:
 * state_Default_walking
 * state_Dancing_walking
 * state_Fighting_walking

Idle
Idle scenes are triggered when you are not active for several minutes in a row. Idle scenes can be associated with specific states and should be named state_StateName_sleeping (where StateName is the name of the associated state). If you have a state with no associated idle state, Whirled will show the avatar's current state. In either case, animated ZZZs will be shown coming out of the top of the avatar.

Some example idles:
 * state_Default_sleeping
 * state_Sitting_sleeping

Actions
Actions are avatar behaviors that play once and then return to the current state. Actions are once-off animations that don't persist. Whirled assumes that actions should be run from the Default state. If you want an action to run straight from a non-default state, it will need its own transition.

Some example actions:
 * action_Laugh
 * action_Attack
 * action_Gasp



Transitions
Transitions are special scenes that smooth the change from one scene (state, walk, or action) to another. They will be played through once before beginning the scene called. For example, if the player decides to start dancing, Whirled will play Default_to_Dancing once through before beginning state_Dancing.

You don't need transitions for all or even any of your states. Just transition the ones you want. However, note that the naming convention is different for walking transitions than it is for state or action transitions.

Some example transitions:
 * Transitioning to and from a walk:
 * state_Default_towalking
 * state_Default_fromwalking
 * Transitioning between two states:
 * Default_to_Dancing
 * Dancing_to_Default
 * Transitioning to and from an action:
 * Default_to_Attack
 * Attack_to_Default
 * Dancing_to_Attack
 * Attack_to_Dancing
 * Transitioning to and from idle
 * state_Default_tosleeping
 * state_Default_fromsleeping

Incidentals
Sometimes you want a state to run normally most of the time, but sometimes to play an alternate animation. For instance, in an idle animation, you want the avatar to yawn every so often. Or you may want your dance state to mix up three different looping moves. These are called incidentals, and can be handled with scene naming, just like other animations. Essentially, you split up the state into multiple numbered versions (01, 02, 03...) and then assign each numbered version a percent probability (:05, :80, :66...) so that the versions' probabilities add up to 100. When a given scene is finished, Whirled will randomly choose the next version of the state to be played, based on these probabilities.

Some example incidentals:
 * A standard Default with an occasional variation:
 * state_Default_01:95
 * state_Default_02:05
 * A Dance that mixes three different moves:
 * state_Dance_01:34
 * state_Dance_02:33
 * state_Dance_03:33

Avatar Code
Just as a typical Whirled avatar is built in Adobe Flash CS3, the code to handle avatar events is written in Flash's ActionScript. Moving beyond the basic avatar template doesn't require complex code writing. Setting up new actions for your avatar is usually as easy as cut and paste.
 * 1) If you haven't yet, download and setup the Whirled SDK.



Required ActionScripts
Whirled avatars require some ActionScript to communicate with Whirled's servers and let each other know what's going on. The basic code tells the avatar which way it's facing and whether or not it's walking. This avatar foundation code is a combination of imported scripts from the Whirled SDK and a few lines of ActionScript in the main scene. In the template we already did this for you. If you make an avatar from scratch, or open the source file for someone else's avatar, you'll need a basic understanding of how to set it up yourself.

Basic ActionScript for the Main Scene
The Main scene of your avatar file should contain all the code for handling avatar behavior in Whirled. For a basic avatar, this is a simple copy and paste.

import flash.events.Event; import com.whirled.AvatarControl;
 * 1) Select the scene "main". If this is a new file, double-click "Scene 1" to rename it "main".
 * 2) Open the Actions window (F9).
 * 3) Paste in this code:

if (_ctrl == null) { _ctrl = new AvatarControl(this); _body = new Body(_ctrl, this, w); _ctrl.addEventListener(Event.UNLOAD, handleUnload); function handleUnload (... ignored) :void { _body.shutdown; } }

var _ctrl :AvatarControl; var _body :Body;
 * 4. Replace w with the width of your scene.



Hotspot
The hotspot determines where the avatar sits on the floor of a room. The default hotspot is the center of the lowest point on the avatar. _ctrl.setHotSpot(x, y);
 * 1) Add this line of ActionScript directly under your existing "_ctrl..." lines.
 * 2) Click the Info tab.
 * 3) Move your cursor over the point on the "floor" directly below your avatar's center of gravity.
 * 4) Note the coordinates of your cursor in the Info tab.
 * 5) Replace the x and y in the script with the x and y coordinates of your newfound hotspot.

Move Speed
The move speed is the rate at which your avatar will traverse a room at full size, in pixels per second. The default move speed is 500. Lower numbers are slower and higher numbers are faster. _ctrl.setMoveSpeed(n); Upload to Whirled and check your walk speed in action. Then go back to your source file and adjust up or down. The number "n" may not be less than 50.
 * 1) Add this line of ActionScript directly under your existing "_ctrl..." lines.
 * 2) Replace the n in the script with the speed you want for your avatar.

State-Specific Actions
You can set up an avatar so that certain actions are only available during certain states. This is useful if you would like to create sets of actions that only appear during suitable states (for example, a "Blow Bubbles" action that can only be used in the "Scuba Gear" state.)

Using this example, lets assume the avatar has no other actions. To set this up correctly, your state_Default scene would contain _ctrl.registerActions; This unregisters all actions whenever your Default scene is triggered, removing "Blow Bubbles" (and any other actions) from the user's selection.

After this, you would add the following to your "Scuba Gear" scene: _ctrl.registerActions("Blow Bubbles"); This makes those actions available again.

Actions must be enclosed in quotation marks, and multiple actions are seperated by commas.

You can also use this method to lock out states, using registerStates instead.

Non-flipping Scenes
The default Body.as file automatically flips all scenes when an avatar faces right. If you'd like a specific scene to always face the same direction, the following code will reverse the flipping. That scene will always look exactly as drawn no matter how a player walks around. //Don't Flip if (_ctrl.getOrientation < 180) { this.x = 0; this.scaleX = 1; }

Automatically Flying
This is code that you can use to make your avatar float automatically in certain states. To use it, add the following to your Main scene: //Change the 0.2 below to change how high above the floor the avatar will appear once it is moved. 0 is the floor and 1 is the ceiling function fly:void{ updateRoom; flyHeight = (roomSize[1] as int)*0.2; _ctrl.setPreferredY(flyHeight); }

function unFly:void{ _ctrl.setPreferredY(0); }

function updateRoom:void{ roomSize = _ctrl.getRoomBounds; }

var flyHeight:int = 0; var roomSize:Array = new Array(100,100,100); On transitions to scenes where the avatar should fly, or scenes where the avatar should be flying, add the following code: fly; On transitions to scenes where the avatar should land, or scenes where the avatar should be on the ground, add the following code: unFly;

Automatically Walking on the Ceiling
Similar to the code above, you can make your avatar hang from the ceiling. In this case, your avatar will be upside down and you will need to remember to set your HotSpot at the top of the scene. function fly:void{ updateRoom; flyHeight = (roomSize[1] as int)*1; _ctrl.setPreferredY(flyHeight); }

function unFly:void{ _ctrl.setPreferredY(0); }

function updateRoom:void{ roomSize = _ctrl.getRoomBounds; }

var flyHeight:int = 0; var roomSize:Array = new Array(100,100,100); On scenes where the avatar should hang from the ceiling, add the following: fly; On scenes where the avatar should be on the ground, add the following: unFly;

If you want to have a mix of states that show the avatar on the floor and on the ceiling, you may want to make a transition between the two. Changing the preferred Y won't automatically move the avatar to a new location, so you will need to tell it to move. To do this, you'll want to add these variables on the main scene: var myLocation:Array = [0.0,0.0,0.0] var myDirection:Number = 180; And you'll want to add this code to the transition to your hanging state (for the transition from the hanging state, replace the 1.0 with 0.0): myLocation = _ctrl.getLogicalLocation; myDirection = _ctrl.getOrientation; _ctrl.setLogicalLocation (myLocation[0],1.0,myLocation[2],myDirection);

Adding an About Action
This code will allow the user to click an action and view a popup. This action is only visible in the inventory and shop listing screen, the idea being that it's a description built into the avatar file itself. It should not interfere with any version of Body.as or MovieClipBody.as that you may be using.

First, make a new movieClip that shows exactly what you want to see in the About Popup. Click on the Properties of it in the library, and export it for ActionScript. Make sure the class name is AboutPopup.

You'll need to add three chunks of code in your main scene: import com.whirled.ControlEvent; import com.whirled.EntityControl; //Create a new instance of the AboutPopup movieClip and name it aboutPopup var aboutPopup = new AboutPopup;
 * Below your import... lines, add this code:

//Check where the avatar is loaded. If it is in the shop or inventory viewer, register your actions and the About action _environment = _ctrl.getEnvironment; if (_environment == EntityControl.ENV_VIEWER || _environment == EntityControl.ENV_SHOP){ _ctrl.registerActions("Victory","About"); _ctrl.addEventListener(ControlEvent.ACTION_TRIGGERED, triggerAbout); }
 * Just under the setMoveSpeed(...) line, add the following code (You must change "Victory" to include the names of all your actions, for example "Attack","Die","Juggle"):

function triggerAbout(event:ControlEvent):void{ if (event.name == "About"){ //Edit the numbers at the end of this line to be the width and height of your AboutPopup movieClip _ctrl.showPopup("Info:", aboutPopup, 200, 75 ); } }
 * At the bottom of the code (above the var... lines), add:

var _environment :String;

Adding an Outline
To create an outline around your entire avatar, add the following code to your main scene: filters = [new GlowFilter(0x000000, 1, 5, 5, 5)];

To remove the outline, simply add the following code when you want to toggle it off: filters = [];

State Changed Code
To make certain codes run when you change states make a new layer in the main scene and use this code: import com.whirled.ControlEvent; ///Only import ControlEvent if you haven't already

_ctrl.addEventListener(ControlEvent.STATE_CHANGED, stateChanged);

function stateChanged(event:ControlEvent):void { switch(event.name) { case "Fly": ///What will happen if we're in the state Fly? ///Hotspot changes so the name is higher _ctrl.setHotSpot(250, 350, 700); ///Change speed so its faster when in this state _ctrl.setMoveSpeed(450); break; default: ///What happens if we're in any other state/default? ///Hotspot changes back if in any other state _ctrl.setHotSpot(250, 350, 600); ///Speed changes to default _ctrl.setMoveSpeed(300); break; } }

Action Triggered Code
To make certain codes run when you play actions make a new layer in the main scene and use this code: import com.whirled.ControlEvent; ///Only import ControlEvent if you haven't already

_ctrl.addEventListener(ControlEvent.ACTION_TRIGGERED, actionTriggered);

function actionTriggered(event:ControlEvent):void { switch(event.name) { case "Speak": ///What happens when this action is played? ///The symbol with the instance name "Face" plays the frame with the label "speak" Face.gotoAndPlay("speak"); break;

} }

Avatar Spoke Code
To make an action/code to play when your avatar has spoken, make a new layer in the main scene and add this code: import com.whirled.ControlEvent; ///Only import ControlEvent if you haven't already _ctrl.addEventListener(ControlEvent.AVATAR_SPOKE, startTalking);

function startTalking(event:ControlEvent):void { ///This is what the avatar does when it talks ///The symbol with the instance name "Face" plays the frame with the label "Talk" Face.gotoAndPlay("Talk"); }