BS Collaborate — Adding chat functionality

Overview

This tutorial explains how to add chat functionality to your multi-user scenes. Basically this is accomplished by adding some files to the web space and referencing them with an ExternProto statement. Therefore this tutorial consists of only one step.

For reference information about BS Collaborate and the nodes supporting it see BS Collaborate documentation.

The example scene can be downloaded as a ZIP archive. It connects with a test BS Collaborate server on test.bitmanagement.de.

There is also a test version of the BS Collaborate server available from our download center. For using the test server you must modify the address in the content files from "test.bitmanagement.de" to "localhost" and adopt the port number.

Download

BS_Collaborate-AddingChat.zip - the whole tutorial.
BS_Collaborate-ChatCode.zip - the code that you need to add to your scene for having a chat window.

BS Collaborate — Adding chat functionality

To add chat functionality all you have to do is:

• Connect your scene with BS Collaborate, as specified in the BS Collaborate — Making a Scene MultiUser tutorial.
• Author a chat GUI or modify the one provided in this tutorial.
• Connect the hasSaid and meSay events of the BSCollaborate node with the GUI.

To use the chat GUI as provided here, add the following code to your multi-user scene, where MU is the DEF name of the BSCollaborate node:

EXTERNPROTO Chat
[
    exposedField SFFloat   height         # 3
    exposedField SFFloat   width          # 10
    eventOut     MFString  meSay
    eventIn      SFNode    hasSaid
    eventIn      SFBool    focus          # enables text input if true.
    eventIn      SFTime    startAnimation
    field        SFBool    initiallyShown # TRUE
]
  "Chat.wrl#Chat"


DEF Chat Chat
{
}


ROUTE Chat.meSay TO MU.meSay
ROUTE MU.hasSaid TO Chat.hasSaid

The BSCollaborate node has an eventIn meSay of type MFString. When the scene sends a string to this field, this means that the local user wants to send a chat message. It is an MFString rather than an SFString, so that you can implement things like smileys or multi-line input. This event is then distributed to all other clients, where the scene can receive it via the hasSaid eventOut.

The hasSaid eventOut of the BSCollaobrate node sends an event to the scene every time a user participating in the scene has sent a chat message. This includes local messsages (those that the scene has previously sent to the meSay eventIn). The value that is sent is an SFNode containing information about who has "said" something, what this user has said, and other information BS Collaborate maintains about a user, including application specific info. More precisely, it sends a reference to the UserData that is maintained for the respective user in the BSCollaborate.users MFNode field. This UserData node is described in the BS Collaborate — Making a Scene MultiUser tutorial, step 4.

It is important, that if the local user enters a message in the chat GUI, the chat GUI sends it to the meSay eventIn of the BSCollaborate node and relies on the message comming back from the server through the hasSaid eventOut, rather than displaying local messages directly. This is (a) to ensure that all users see chat messages in the same order (as received by the server), and (b) to not display local messages twice.

When a scene receives a hasSaid event it should look at the nickname, sessionId or idx field, in order to find out who has said something, so that it can display an appropriate message. The code that is used for this in this example looks essentially like the following:

DEF MsgConverter Script
{
    eventIn SFNode hasSaid

    field MFString ChatHistory

    url "vrmlscript:

    function hasSaid(User)
    {
        var HistLine= '['+ User.nickname +']: '+ User.chat;
        ChatHistory[ChatHistory.length]= HistLine;

        Update();
    }

    "
}

ROUTE MU.hasSaid TO MsgConverter.hasSaid