Avatar

Kind of class:public class
Package:com.smartfoxserver.openspace.engine.model.avatar
Inherits from:MovieClip
Author:The gotoAndPlay() Team
http://www.openspace-engine.com
http://www.smartfoxserver.com
http://www.gotoandplay.it
Classpath:com.smartfoxserver.openspace.engine.model.avatar.Avatar
File last modified:Thursday, 02 December 2010, 14:43:43
The Avatar class is the base class used to implement the users' main and ghost avatar classes.

OpenSpace does not provide a default avatar implementation. Developers must create their own custom avatar classes as described in the implementation notes below. These classes are then instantiated by OpenSpace when avatars are created during (or after) the map rendering process.
Implementation note:
  • A custom Avatar can be created by following this workflow. Please notice that the Flash version of the OpenSpace component must be installed, even if we are developing a Flex application.
    1. Create a new ActionScript class in an external AS file: the class must extend the Avatar class described here, which in turn extends flash.display.MovieClip, like in the following example:
      package my.own.package
      {
          import com.smartfoxserver.openspace.engine.model.avatar.Avatar;
          import com.smartfoxserver.openspace.shared.view.items.Tile;
      
          public class DemoAvatar extends Avatar
          {
              public function DemoAvatar()
              {
      
              }
          }
      }
    2. Create a new FLA file in the Flash authoring tool containing all the graphical assets that will be used to render the avatars: the resulting SWF file after compilation will constitute the avatars library to be loaded by our application and passed to the OpenSpace.avatarAppDomain property (check the property documentation for more informations); in case we don't want to use external SWF files to be loaded at runtime, we can:
      » Flash: create the avatar assets and classes inside the library of our main FLA file;
      » Flex: still create avatar assets and classes inside an external FLA, but export it to an SWC following the "Flex Component Kit for Flash" guidelines: adding the SWC to the Flex project's Build Path will make the avatar classes available to our application (this approach is NOT recommended as it can lead to some issues in case the avatar must be customized at runtime).
    3. In the Flash Components panel, locate the AvatarLibrary component within the OpenSpace 2 folder and drag it in the Library panel: this is a non-visual component containing the Avatar and Tile classes that we will need in order to be able to compile the FLA file.
    4. In the Library panel, create a new Symbol of type "Movie clip". In the linkage section flag the "Export for ActionScript" checkbox and enter the name of the class created previously in the "Class" field (while the "Base class" field must remain empty). We have to make sure that Flash validates our class by clicking the validation button; if validation returns an error, we have to set the classpath properly in our FLA settings (so that Flash is able to "see" that class).
    5. Go back to our class code and override the methods described below to control the appearance of our avatar in response to calls made by OpenSpace internally. For example we will need to instantiate the graphical assets from the avatars library FLA file to handle different skins for different movement directions and actions, and other assets like chat balloons, name textfield, etc (see also usage notes below). Please notice that the graphical assets should be aligned on the stage so that the avatar feet (or anything else representing the most bottom part of the avatar, or its projection on the ground in the tile space) are centered at the (0,0) coordinates of the avatar movieclip.
    6. Export the final SWF file (or SWC file, see previous step 2).
    Multiple avatar classes can be created in the same FLA file, corresponding to different avatar types to be defined in the OpenSpace server-side configuration as described in the usage notes.
Usage:
  • In OpenSpace, in order to create the player's avatar, the IOpenSpaceAPI.createMyAvatar method must be called. The parameters object passed to this method contains, among the others, the type of the avatar that should be created.
    Available avatar types are declared in the OpenSpace server-side configuration as entries in the <AvatarTypes/> section of the configuration file. Each <AvatarType/> entry contains a mandatory mainClass attribute and the optional ghostClass attribute. Both attributes contain the fully qualified name of a custom avatar class implemented following the previous steps.
    Following the example provided in step 1 of the implementation notes, an avatar type entry featuring the main class only might look like this: <AvatarType mainClass="my.own.package.DemoAvatar">demo</AvatarType>
    The server-side configuration is received by OpenSpace during initialization; later, when the avatar creation is requested and the avatar type is passed, OpenSpace retrieves the class (or classes) associated with that type and and instantiates it (or them).

    Main avatar and ghost avatar
    Why can each avatar type be linked to two classes, "main" and "ghost"? The main avatar is the standard avatar which OpenSpace places on the map: it represents a user (a real one or a Non-Player Character too) and can be moved around in the isometric environment, following the z-sorting rules of OpenSpace. Its graphics are usually updated as the values of the direction, skin and state properties change, or in response to calls to the overridible methods described below.
    The ghost avatar is an additional (optional) avatar which OpenSpace creates on a layer on top of all the map elements (background, tiles, foreground). In this way, the graphical assets it contains are always visible, even if the main avatar is, for example, behind a building. The ghost follows the main avatar during its movement on the map. It usually contains assets which don't change together with the main avatar's direction, skin, state, action, etc, like a chat balloon, or the user name. Also, if the <EnableBringGhostToFront> parameter in the OpenSpace client-side configuration is set to 1, when a ghost avatar is clicked OpenSpace brings it above the other ghosts; this can be useful in case the ghosts contain the chat balloons and the user still needs to be able to read them even if they are overlapping.
    Both the main and the ghost classes must extend the base Avatar class, or the avatar creation process will be interrupted (and an error message logged).

Summary


Instance properties
  • id : int
    • The avatar's id.
  • type : String
    • The avatar type.
  • isMyAvatar : Boolean
    • Avatar's player ownership.
  • isGhost : Boolean
    • "Ghost" avatar kind.
  • avatarName : String
    • Avatar's name.
  • controlAreaWidth : int
    • The width of the avatar's control area.
  • px : int
    • Position of the avatar along the isometric grid x axis.
  • py : int
    • Position of the avatar along the isometric grid y axis.
  • pz : int
    • Position along the isometric grid z axis (elevation).
  • isEditing : Boolean
    • Avatar's owner is editing the current map.
  • direction : int
    • Current direction faced by the avatar.
  • currentAnimTime : int
    • Current duration of the avatar movement from tile to tile along N/E/S/W directions.
  • skin : Object
    • An Object describing the current avatar's graphical appearance.
  • state : Object
    • An Object describing the current avatar' state.
Instance methods
  • init : void
    • Initialize the avatar.
  • destroy : void
    • Destroy the avatar.
  • toString : String
    • A string representation of the avatar.
Event handlers
  • onMovementStart (tile:Tile, triggers:Array) : void
    • Listener called when the avatar starts moving.
  • onMovementPause : void
    • Listener called when the map scrolling begins.
  • onMovementResume : void
    • Listener called when the map scrolling ends.
  • onMovementStop (tile:Tile, triggers:Array) : void
    • Listener called when the avatar stops moving.
  • onEnterTile (tile:Tile, triggers:Array) : void
    • Listener called when the avatar enters a tile.
  • onLeaveTile (tile:Tile, triggers:Array) : void
    • Listener called when the avatar leaves a tile.
  • onMessage (message:String, isPrivate:Boolean) : void
    • Listener called when the avatar's owner has sent a public or private message.
  • onCustomAction (data:Object) : void
    • Listener called when the avatar's owner executes a custom avatar action.

Instance properties

avatarName

final public avatarName:String
(read,write)

Avatar's name.
This property is set by OpenSpace when the avatar is initialized before being placed on the map. Its value is set to the AvatarCreationParams.name property value passed to the IOpenSpaceAPI.createMyAvatar method during avatar creation.

This is a read-only property which can't be overridden.
Implementation note:
  • This property can be useful to display the name of the user near his own avatar. Usually the name is rendered by the ghost avatar, to avoid z-sorting issues while the avatar is moving on the map.

controlAreaWidth

final public controlAreaWidth:int
(read,write)

The width of the avatar's control area.
OpenSpace makes use of four control points which "describe" the avatar projection on the ground:

The control points are positioned symmetrically around the (0,0) coordinates of the avatar movieclip, using the tile's height/width ratio to determine the position of top and bottom control points. This property can't exceed the tile's width: if the passed value exceed this limit, or if the property is not set, the default AvatarDefaults.CONTROL_AREA_WIDTH value is applied.
OpenSpace uses the four control points to check the avatar position with respect to the tile, to know whether the avatar has reached the next tile during a movement or not. They are also used to check if the avatar and the surrounding objects do overlap when the <EnablePixelCollisionCheck> parameter is set to 1 in the OpenSpace client-side configuration.
If this property is set to 0, the point corresponding to the (0,0) coordinates of the avatar movieclip is taken into account only. This is usually enough to have an excellent avatar behavior.

This property can't be overridden.
Implementation note:
  • This property should be set in the init method, which is called right after the class is instantiated during avatar creation.

currentAnimTime

public currentAnimTime:int
(read,write)

Current duration of the avatar movement from tile to tile along N/E/S/W directions.
This property is updated by OpenSpace during the avatar movement on the map, reflecting the speed changes due to the terrain configuration or as a result of an IOpenSpaceAPI.setMyAvatarAnimationTime method call.
The animation duration is expressed in milliseconds. A correction is applied for the other directions, to make the avatar have the same speed when moving in any direction.
Implementation note:
  • The getter and setter methods of this property should be overridden to modify the internal animation speed of the avatar (for example the speed of its feet during the walk) to match the avatar movement speed on the map (to avoid a "sliding avatar" effect).
    Please notice that this property shouldn't be set directly, because its effects would be visible on the current client only, without being broadcasted to the other clients.

direction

public direction:int
(read,write)

Current direction faced by the avatar.
This property is set by OpenSpace during the avatar movement on the map each time its direction changes.
Valid values are contained in the AvatarDirections class.
Implementation note:
  • The getter and setter methods of this property should be overridden to adjust the avatar graphics accordingly to the faced direction.
    Please notice that this property shouldn't be set directly, because its effects would be visible on the current client only, without being broadcasted to the other clients.
See also:

id

final public id:int
(read,write)

The avatar's id.
This property is set by OpenSpace to the SmartFoxServer user id value when the avatar is initialized.

This is a read-only property which can't be overridden.

isEditing

public isEditing:Boolean
(read,write)

Avatar's owner is editing the current map.
This property is set to true or false by OpenSpace when the owner of the avatar enters or leaves EDIT MODE respectively.
Implementation note:
  • The getter and setter methods of this property should be overridden to give a visual feedback to all the users that one of them is currently editing the current map. For example the avatar could become semi-transparent, as to say that its owner is now busy and is not able to interact with the other users.
    Please notice that this property shouldn't be set directly, because its effects would be visible on the current client only, without being broadcasted to the other clients.

isGhost

final public isGhost:Boolean
(read,write)

"Ghost" avatar kind.
During avatar initialization this property is set to true if the avatar class is used by OpenSpace to render the ghost avatar, according to what is defined for the current avatar type in the OpenSpace server-side configuration.

This is a read-only property which can't be overridden.

isMyAvatar

final public isMyAvatar:Boolean
(read,write)

Avatar's player ownership.
This property is set by OpenSpace when the avatar is initialized before being placed on the map. If the avatar is created by the current client by means of the IOpenSpaceAPI.createMyAvatar method, this property is set to true and the avatar belongs to the current player. Avatars belonging to the other users on the current client have this property set to false.

This is a read-only property which can't be overridden.
Implementation note:
  • This property can be used to display a marker (for example a circle around avatar's feet) to help the player identify his own avatar among the others.

px

final public px:int
(read)

Position of the avatar along the isometric grid x axis.


This property can't be overridden.

py

final public py:int
(read)

Position of the avatar along the isometric grid y axis.


This property can't be overridden.

pz

final public pz:int
(read)

Position along the isometric grid z axis (elevation).


This property can't be overridden.

skin

public skin:Object
(read,write)

An Object describing the current avatar's graphical appearance.
This property is set by OpenSpace when the IOpenSpaceAPI.setMyAvatarSkin method is called on the client of the avatar's owner.
Implementation note:
  • The getter and setter methods of this property should be overridden to adjust the avatar graphics accordingly to the custom parameters contained in the passed Object. This object can contain any number of custom parameters describing the avatar's appearance: for example a boolean value to differentiate between male and female, a string for the race, a string (usually a code) for a specific shirt, etc.
    Please notice that this property shouldn't be set directly, because its effects would be visible on the current client only, without being broadcasted to the other clients.

state

public state:Object
(read,write)

An Object describing the current avatar' state.
This property is set by OpenSpace when the IOpenSpaceAPI.setMyAvatarState method is called on the client of the avatar's owner.
Implementation note:
  • The getter and setter methods of this property should be overridden to adjust the avatar graphics accordingly to the custom parameters contained in the passed Object. This object can contain any number of custom parameters describing the avatar' state: for example a string containing "sitting", or "sleeping". The intended usage of the state is to describe a permanent condition, not a temporary action. See the onCustomAction event listener for more informations.
    Please notice that this property shouldn't be set directly, because its effects would be visible on the current client only, without being broadcasted to the other clients.

type

final public type:String
(read,write)

The avatar type.
The avatar type, as defined in the <AvatarTypes/> section of the OpenSpace server-side configuration, to which the current avatar class is associated.

This is a read-only property which can't be overridden.

Instance methods

destroy

public function destroy (
) : void

Destroy the avatar.
This method is called by OpenSpace when the avatar is removed from the map.
Implementation note:
  • This method should be overridden to dispose all the avatar's internal data structures, event listeners, etc., to let the Garbage Collector destroy the class instance properly when executing its task.
    Please notice that this method shouldn't be called directly.

init

public function init (
) : void

Initialize the avatar.
This method is called by OpenSpace when the avatar is created.
Implementation note:
  • This method should be overridden to set the initial values of some avatar settings (for example the controlAreaWidth property) and the initial avatar appearance. When this method is called, OpenSpace has already set all the properties it is in charge of, so the initial skin, state, direction, isMyAvatar, etc. values are available to display the proper avatar graphics.
    Please notice that this method shouldn't be called directly, because its effects would be visible on the current client only, without being broadcasted to the other clients.

toString

override public function toString (
) : String

A string representation of the avatar.
Returns:
  • a string with this format: Avatar id (user:avatarName / type:type).
Overrides:
  • MovieClip.toString

Event handlers

onCustomAction

public function onCustomAction (
data:Object) : void

Listener called when the avatar's owner executes a custom avatar action.
This property is set by OpenSpace when the IOpenSpaceAPI.setMyAvatarAction method is called on the client of the avatar's owner.
Implementation note:
  • This method should be overridden to adjust the avatar graphics accordingly to the custom parameters contained in the passed Object. This object can contain any number of custom parameters describing the avatar's action: for example a string containing "applauding", or "laughing".
    The "avatar action" represents an event with a limited duration in time (e.g. the avatar applauding), not a permanent state of the the avatar (e.g. the avatar sitting on a chair). This means that all users entering the map after an existing avatar has begun performing an action won't be able to see that action. Permanent states should be handled by means of the state property.
    Please notice that this property shouldn't be set directly, because its effects would be visible on the current client only, without being broadcasted to the other clients.

onEnterTile

public function onEnterTile (
tile:Tile, triggers:Array) : void

Listener called when the avatar enters a tile.
This method is called by OpenSpace whenever the avatar enters a new tile during its movement along a path.
If the tile entered by the avatar has one or more associated TriggerType.AVATAR_ENTER triggers, they will be passed to the listener.
Parameters:
tile :
the Tile object corresponding to the tile entered by the avatar.
triggers:
a list of Trigger objects associated with the tile.
Implementation note:
  • This method should be overridden to display the proper avatar's graphics depending on the properties of the entered tile (for example the Tile.terrain).
    Please notice that this listener shouldn't be called directly because: 1) this action could be out-of-sync with respect to the movement of the avatar on the map, and 2) its effects would be visible on the current client only, without being broadcasted to the other clients.

onLeaveTile

public function onLeaveTile (
tile:Tile, triggers:Array) : void

Listener called when the avatar leaves a tile.
This method is called by OpenSpace whenever the avatar leaves a tile during its movement along a path.
If the tile left by the avatar has one or more associated TriggerType.AVATAR_LEAVE triggers, they will be passed to the listener.
Parameters:
tile :
the Tile object corresponding to the tile left by the avatar.
triggers:
a list of Trigger objects associated with the tile.
Implementation note:
  • This method should be overridden to display the proper avatar's graphics depending on the properties of the left tile (for example the Tile.terrain).
    Please notice that this listener shouldn't be called directly because: 1) this action could be out-of-sync with respect to the movement of the avatar on the map, and 2) its effects would be visible on the current client only, without being broadcasted to the other clients.

onMessage

public function onMessage (
message:String, isPrivate:Boolean) : void

Listener called when the avatar's owner has sent a public or private message.
This method is called by OpenSpace whenever the user who owns the avatar sends a public or private message through a call to the relevant SmartFoxServer API method.
Parameters:
message :
the message text.
isPrivate:
the message type; true if the message is private, false if it is public.
Implementation note:
  • This method should be overridden to display the message text, for example inside a balloon contained in the ghost avatar.
    Please notice that this method shouldn't be called directly, because its effects would be visible on the current client only, without being broadcasted to the other clients.

onMovementPause

public function onMovementPause (
) : void

Listener called when the map scrolling begins.
This method is called by OpenSpace whenever a map scrolling is started, and all the moving avatars are temporarily stopped.
Implementation note:
  • This method should be overridden to pause the avatar animation lanched when the onMovementStart listener was called. The reasons for pausing the avatar are: 1) avoiding to show an animation while in fact the avatar position is not changing; 2) avoiding an additional overhead during the already CPU-intensive map scrolling.
    Please notice that this listener shouldn't be called directly because: 1) this action could be out-of-sync with respect to the movement of the avatar on the map, and 2) its effects would be visible on the current client only, without being broadcasted to the other clients.
See also:

onMovementResume

public function onMovementResume (
) : void

Listener called when the map scrolling ends.
This method is called by OpenSpace whenever a map scrolling is completed, and all the previous avatars movements are resumed.
Implementation note:
  • This method should be overridden to resume the avatar animation paused when the onMovementPause listener was called.
    Please notice that this listener shouldn't be called directly because: 1) this action could be out-of-sync with respect to the movement of the avatar on the map, and 2) its effects would be visible on the current client only, without being broadcasted to the other clients.
See also:

onMovementStart

public function onMovementStart (
tile:Tile, triggers:Array) : void

Listener called when the avatar starts moving.
This method is called by OpenSpace whenever the avatar, previously standing on the current tile, starts moving along a path.
If the tile on which the avatar is standing has one or more associated TriggerType.AVATAR_MOVE triggers, they will be passed to the listener.
Parameters:
tile :
the Tile object corresponding to the tile on which the avatar is currently located.
triggers:
a list of Trigger objects associated with the tile.
Implementation note:
  • This method should be overridden to display the proper avatar's movement animation (i.e. walk, run, swim, etc.) in the proper direction. Of course the actual position of the avatar on the map is updated by OpenSpace; the avatar should display the proper animation only.
    Please notice that this listener shouldn't be called directly because: 1) this action could be out-of-sync with respect to the movement of the avatar on the map, and 2) its effects would be visible on the current client only, without being broadcasted to the other clients.

onMovementStop

public function onMovementStop (
tile:Tile, triggers:Array) : void

Listener called when the avatar stops moving.
This method is called by OpenSpace whenever the avatar, previously moving along a path, stops on the current tile.
If the tile on which the avatar stops has one or more associated TriggerType.AVATAR_STOP triggers, they will be passed to the listener.
Parameters:
tile :
the Tile object corresponding to the tile on which the avatar is currently located.
triggers:
a list of Trigger objects associated with the tile.
Implementation note:
  • This method should be overridden to stop the avatar's internal movement animation (i.e. walk, run, swim, etc.).
    Please notice that this listener shouldn't be called directly because: 1) this action could be out-of-sync with respect to the movement of the avatar on the map, and 2) its effects would be visible on the current client only, without being broadcasted to the other clients.