Before you read

• It may be useful to read Simple Chat
• Read How to Install an Extension
• Find the AvatarChat example files in [installation folder]/game_examples/AvatarChat

 

Overview

In this tutorial we will explain how to customize the Avatar Chat example to fit your own needs: plugin, AS3 client, and Unity client.  An avatar chat application is one where users see some type of character on the screen for each user in the room.  This character usually has the ability to move, and possibly change the image displayed or switch to a different animation.

 

Live Example

You can view a live example of the AS3 Avatar Chat and the Unity Avatar Chat.  AS3 clients and Unity clients are not in the same room; it is possible to do this but unusual for an application to want to and the X,Y coordinates of the AS3 clients don't match the X,Y,Z coordinates of the Unity clients.

 

Install the Extension

The example extension is configured for use with the AS3 client.  The Unity client can use this, however performance will be improved if you edit Extension.xml and set checkChatForTriggerEvents to false.  This was not implemented as a GameManager game (although it would be easy to do so), which means that you do not need any server level components.  After installing the extension, the example clients can be used with no modification other than possibly editing the settings.xml file to point to the correct IP and port.

 

Details of the Extension.xml variables:

• queueFrequency: specifies the number of milliseconds to wait between sending batches of queued messages to clients.
• sendUserEnterExitEvents: if the room is configured to send room events to clients, then you can turn this off.  When set to true, it sends a queued plugin message to the room announcing each user entering or leaving the room.
• checkChatForTriggerEvents: when set to true, any chat in the room is processed using the EmoChatFilter and if one of the words in the line of chat is one of the words in the chat filter, a message is broadcast to the room.  In the AS3 client, this can change the color of the user's avatar and the text displayed on the avatar, and possibly the rotation of the avatar.  The example Unity client ignores the emotions since its 3D avatar does not have the ability to smile, frown, etc.

 

Plugin Requests

The AvatarChatPlugin is extremely flexible and can fill the room plugin needs of many rooms that are not games, simply by editing the Extension.xml for it.  Here are the plugin requests that it can handle.

• USER_LIST_REQUEST: responds to the client with an EsObject array containing information about each user in the room, including the most recent position update and most recent avatar state.
• POSITION_UPDATE_REQUEST: records the position update for this user, and broadcasts a queued message to the room with the update.  Any information on the request will be included in the broadcast message.  Optional boolean variables on the request can tell the plugin to send the broadcast immediately rather than queued, or to send it UDP.  If you include an optional queue label on the request, only the most recent message with that queue label will be delivered when the queue is sent to users, which is good when the client just needs to know the most recent position rather than the actual path the avatar is taking to get there.
• AVATAR_STATE_REQUEST: similar to the position update request, this records the avatar state then broadcasts it to the room, giving whatever information is needed so that clients can display the correct image.  This request also has the optional booleans for immediate sending rather than queued, UDP, and the optional queue label.
• BROADCAST_REQUEST: relays the message to the room without recording.  Optional variables specify whether the message should be delivered immediately, and if not what the queue label is, if any.
• BROADCAST_UDP_REQUEST: similar to the broadcast request, relays the message immediately using UDP.  No optional variables.

 

AS3 Client

After the client connects and logs in, it sends a CreateRoomRequest for a room that has the AvatarChatPlugin attached.  Most of the ES5 code at this point is in ChatRoomScreen.as.  After joining the room, the client requests a user list, then uses this to display avatars for each of the users in the room, in the correct location and showing the correct color, etc.  The client sends a position update on joining the room and when the user clicks to move, but doesn't use any of the other plugin requests.  The avatar state events are triggered by chat messages.  User enter and exit messages are broadcast to the room, queued, so that clients know to add or remove avatars.

 

Unity Client

The Unity client similarly connects, logs in, and sends a CreateRoomRequest for a room that has the AvatarChatPlugin attached.  Most of the ES5 code at this point is in NetworkController.cs.  After joining the room, the local player is spawned and the client requests a user list.  The user list is then used to spawn avatars for the other users, using the remotePlayerPrefab found in the Network Assets folder.  Position updates are sent whenever the local player notices that its position or rotation has changed, which means a lot of position updates are sent.  (see NetworkTransform.cs) The plugin broadcasts them queued which saves some bandwidth.  Avatar state requests are sent when the local player changes its animation state.  (see AnimationSynchronizer.cs and ThirdPersonController.js).  Chat messages are displayed but if the plugin sends avatar state events triggered by chat the emotion changes are ignored.  User enter and exit messages are broadcast to the room, queued, so that clients know to add or remove avatars.

 

How to Handle Vertical Positions

The Avatar Chat example is flat so there's no need to change the Y coordinate.  If you need to be able to send position updates for 3D, it's simple.  In NetworkTransform.getPlayerPosition, find the line containing POSITION_Y which is commented out.  Uncomment it, and comment the line immediately below it which is a hard coded value for Y.

 

Choice of Avatars

Most games that have avatars allow users to choose an avatar before joining the game.  See Rejoin Game for how to do that.