Step 2 — Connecting to BS Collaborate

To make a scene multi-user capable you need to add a NetConnection node and a BSCollaborate node. The NetConnection node specifies the hostname and port number of the BS Colloaborate server to contact to, and the BSCollaborate node names the room that the X3D scene should join on the server and manages the session state (see Step 4 - Managing User Sessions)

The NetConnection Node

The NetConnection node is defined in the following way, conforming to the NetworkSensor proposal discussed by the Web3D consortium in 2006.

NetConnection
{
    field    SFBool    enabled  TRUE
    eventOut SFBool    isActive

    field    MFString  address  "localhost"
    field    SFInt32   port     0
    field    SFInt32   protocol 0
    field    SFTime    timeOut  0
    field    SFBool    secure   TRUE
}

For a BS Collaborate scene the fields timeOut and secure are ignored by BS Contact, and the protocol field should be set to 3 in order to select the BS Collaboarate protocoll. BS Collaborate connections are allways secured via encryption, and the timeOut value is irrelevant because BS Contact uses its own, elaborate algorithm that tries to tunnel the traffic through HTTP if a direct TCP connection is unavaillable and it tries to reconnect to the server if the connection is lost (not yet available as of version 7.105).

So the typical usage of a NetConnection node looks like this:

DEF Conn NetConnection
{
    address  "test.bitmanagement.de"
    port     12345
    protocol 3      # don't forget to set 3 here.
}

The BSCollaborate Node

The BSCollaborate node is defined in the following way:

DEF MU BSCollaborate
{
    field SFNode connection "NULL"  # assign a Connection node here.

    field SFString roomName "MU Tutorial"


    eventIn   MFString   tryLogin
    eventIn   SFTime     logOut
    eventOut  SFBool     loginResult
    eventOut  SFInt32    sessionId
    eventOut  SFNode     hasJoined
    eventOut  SFNode     hasLeft

    eventIn   SFVec3f    ownPosition
    eventIn   SFRotation ownOrientation
    eventOut  SFNode     hasMoved

    eventIn   MFString   meSay
    eventOut  SFNode     hasSaid

    field     MFNode     users       []
}

The BSCollaborate node specifies which room on the server a scene should be associated with, and sends and receives events to/from the scene required for:

authenticate the own user with the server (something like sending username and password to the server and receiving an access granted or denied)
session management (notifies the scene when other users join or leave the room)
avatar management (position, display)
chat

There can be only one BSCollaborate node in the scene. Its fields are explained in the following steps of this tutorial.

In the console you can see that the isActive field of the NetConnection node sends a TRUE when the connection has been established successfully. This however just means that there is a communication possible. It does not mean that the user has been authenticated to join the room (see Step 3 - Authenticating with BS Collaborate).