Step 5 — Displaying avatars

This step adds the scripts necessary to display avatars. BS Collaborate does not display avatars by itself, but relies on the content to do so. This allows for maximum flexibility, for example if avatars should have more complex behaviour or if other features should be added.

In the previous step we have seen that the BSCollaborate maintains a node with info about a user for each user. This node is called UserData. It has one field wich is of type SFNode and is not used by BS Collaborate. This field is named 'userData' and is provided for the content so that it can maintain custom state info for each user joining the scene.

To display avatars for all users in the scene - not for the own user, however - we define a proto that manages one avatar and we add a Script that receives events from the BSCollaborate node and controlls the instances of that proto. The proto is named AvatarInfo and instances of it are added by the Script to the userData field of the UserData node. The Script is named ScrAvatarMgr.

This is the interface description of the AvatarInfo Proto:

PROTO AvatarInfo
[
    eventIn SFString    set_avatarString
    eventIn SFVec3f     set_position
    eventIn SFRotation  set_orientation
]

Creating the Avatar

On Initialization the AvatarInfo node receives the avatar string from the UserData node, examines it and loads the corresponding avatar geometry. In this demo version we simply form a relative URL with the statement var Url= 'Avatars/'+ AvStr +'.wrl';.

The script inside the AvatarInfo node issues a createVrmlFromUrl(.) for the avatar and on reception of the avatar geometry the function AvatarLoaded(.) examines the received scene graph of the avatar to see how to set the position and orientation. This mimics the behaviour of BS Contact, which supports avatars that have set_position and rotation eventIns and wrapps them in a Transform node if they don't. Here an application may need to change behaviour if it wants to use other types of avatars.

Updating the position

When the AvatarInfo node receives a position or rotation update it simply forwards this to the avatar in the way the avatar requires it. Since avatars are usually modelled so that you see their face rather than their back when you load them separately, the orientaiton must be combined with a 180 rotation so that the avatar looks into the right direction.

Managing the Avatars

There is a Script node named ScrAvatarMgr which responds to events from the BSCollaborate node in order to display avatars. It responds to the events hasJoined, hasLeft and hasMoved. However the hasLeft event is implemented in a later step of this tutorial.

When the ScrAvatarMgr Script receives a hasJoined event, it examines the passed UserData node to create a new avatar. This involves checking the index whether it is 0, as this means the event is for the local user, which does not need to be displayed (for now). For every other user the script creates an instance of the AvatarInfo node, passes it the avatar string read from the UserData node and assigns the instance to the userData field of the UserData node, so that the instance is associated with the corresponding user. This has no meaning for the BSCollaborate node, as it does not interact with the userData field, but it makes the AvatarInfo node available together with the UserData node every time the BSCollaborate node sends out an event about a user. The script further adds the AvatarInfo node to a Group node, so that it becomes part of the rendered scene graph and can actually display an avatar.

On reception of a hasMoved event the ScrAvatarMgr script simply forwards the position and orientation to the AvatarInfo node associated with the user.

Avatars and the NavigationInfo node

It is important that the avatarSize in the currently bound NavigationInfo matches the size of the avatar that is displayed for the own user in other clients. Especially the avatar hight must match the distance between the avatars eye hight and the sole of the feet. If it does not, the avatar appears in other clients either flying a few centimeters above the ground, or its feet appear stuck in the ground.

Further, avatars should be modeled in a way that the origin of their coordinate system (0, 0, 0) is the point from where an avatar sees the world, i.e. the point between its eyes.