Union User Guide

Rooms

Rooms group clients together in a common activity, such as chatting about a specific topic, playing a game of chess, or receiving updates on a sporting event.

Each room stores shared information in room attributes. By default, all clients in a room are automatically notified of changes to room attributes.

A room is given custom functionality by attaching room modules to it. A room module responds to activity in its associated room by listening for the room's events (eg. a client joined or a message was received). Room modules can also generate their own messages and actions. For example a room module might act as the "main loop" of a game, and send messages to room occupants when the game starts or finishes.

On the server, rooms are created in two ways: at startup in union.xml, or programmatically on the server. Rooms can also be created by client requests, as described separately in the documentation for Union's client frameworks.

Creating Rooms at Startup

Rooms are deployed at startup by adding <room> elements in the <rooms> section of union.xml. For example:

<rooms>
    <room>
        <id>hockeyChat</id>
        <attributes>
            <attribute name="roomTitle">Welcome to Hockey Chat</attribute>
        </attributes>
        <modules>
            <module>
                 <source type="class">hockeymodules.ScoreUpdates</source>
                 <attributes>
                    <attribute name="updateFrequency">10000</attribute>
                 </attributes>
            </module>  
            <module>
                <source type="script">HockeyChatBot.js</source>
            </module>                                
        </modules>
    </room>
</rooms>

The preceding example creates a room with the ID "hockeyChat". The room has one room attribute, "roomTitle", with the value "Welcome to Hockey Chat". The "roomTitle" attribute is sent to all clients that join the room, allowing the client application to use the information. The "hockeyChat" room has two modules. The first module, ScoreUpdates (written in Java), would send score updates to the clients in the room every 10000ms. The second module, ChatBot (written in JavaScript), randomly sends chat messages to all clients in the room.

Configuring Rooms via union.xml

Rooms can be configured with room settings, which are defined using standard room attributes. To change the settings for a room created via union.xml, specify the desired attribute in the <room> tag's attribute list. For example, the following code assigns the password for the room "privateLobby":

<room>
  <id>privateLobby</id>
  <attributes>
    <attribute name="_PASSWORD">secretPass</attribute>
  </attributes>
</room>

For a list of available room settings, see the Field Summary for the Room class documentation. Each field listed corresponds to a setting attribute by the same name, without the prefix "ATTR". For example, the field ATTR_PASSWORD corresponds to the setting attribute _PASSWORD, as shown in the preceding "privateLobby" example.

Creating Rooms Programmatically

To create a room programmatically with custom server-side code, create a RoomDef instance within a server module or a room module, then pass that instance to the Server instance's createRoom() method. For example, the following code creates a room with an auto-generated ID and no attributes or modules:

1
2
RoomDef roomDef = new RoomDef();
Room room = roomContext.getServer().createRoom(roomDef);

Use RoomDef's methods to specify the room's characteristics. For example, the following code specifies a room's ID, settings, attributes, and modules.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
// Create the room def
RoomDef roomDef = new RoomDef();

// Set the ID of the room...if room id is not set a random id will be generated
roomDef.setRoomID("mainChessRoom");

// Set the room attribute to not die on empty
AttributeDef attrDef = new AttributeDef();
attrDef.setName(LocalRoom.ATTR_DIE_ON_EMPTY);
attrDef.setValue(Boolean.FALSE);
attrDef.setFlags(Attribute.FLAG_SHARED);
roomDef.addAttribute(attrDef);

// Set a room attribute for the difficulty of the game room which will not be shared to clients
attrDef = new AttributeDef();
attrDef.setName("gameDifficulty");
attrDef.setValue("hard");
attrDef.setFlags(Attribute.FLAG_SERVER_ONLY);
roomDef.addAttribute(attrDef);
     
// Add the chess room module which will run the game of chess in the room          
ModuleDef modDef = new ModuleDef();
modDef.setType(ModuleDef.CLASS);
modDef.setSource("myrooms.games.ChessRoomModule");
roomDef.addModule(modDef);
       
// Use the room context that was passed to your module to get a reference to the server and create our room        
Room room = roomContext.getServer().createRoom(roomDef);

You can remove rooms from the server by "shutting the room down" as in the following example:

1
2
3
4
5
6
try {
    Room room = roomContext.getServer().getRoom("mainChessRoom");
    room.shutdownRoom();
} catch (RoomNotFoundException e) {
    // room wasn't on server
}