| Unity uClientCore > URoom |
URoom(roomID, namespace)
| addURoomListener(l) | Registers an object to receive URoomListener event notifications. |
| autoClientCount(enabled, interval) | Enables or disables automatic client count retrieval (every interval milliseconds) for this room. |
| clientIsInRoom() | Returns true if the current client is in this room. |
| clientListInited() | Returns true after the client joins the room and the room's client list has been fully received. |
| getAttribute(attrName) | Returns the value of the specified room attribute. |
| getAttributeList() | Returns an object whose properties represent the names and values of the shared attributes for this room. The object is a snapshot of the current attributes; changes that occur after the call to getAttributeList() are not reflected by the object. To read the properties of the object returned, use a for-in loop. For example, the following code prints the attributes for a room to the Flash Output window:
|
| getClientIDs() | Returns an array of the IDs of the clients currently in the room. |
| getFullRoomID() | Returns the room's fully qualified identifier, including its namespace (e.g., "chat.sports.hockey"). |
| getNamespace() | Returns a reference to the NameSpace instance that contains this room. |
| getNumClients() | Asks Unity how many clients are currently in this room. The response is sent via URoomListener.onNumClients(). |
| getRoomID() | Returns the room's id (e.g., "hockey"). |
| join(password) | Asks Unity to add the client to the room. |
| leave() | Asks Unity to remove the client from the room. |
| removeURoomListener(l) | Cancels URoomListener event notifications for an object. |
| setAttributeOnServer(attrName, attrVal, isShared, isPersistent, appendVal) | Asks Unity to set an attribute for this room. If isShared is true, the attribute value is automatically propagated to clients in the room. See URoomListener.onUpdateClientAttribute(). In order to set an attribute on a room, you must be in that room. Note that Unity uses the pipe character ("|") internally to separate attributes during transimission to and from the server. Hence, attribute names and values must not contain the character "|". |
The URoom class represents a Unity room as it exists on the server. Each specific URoom instance is a reflection of an actual server-side Room instance (written in Java). Together, the client-side URoom and server-side Room provide the following basic multiuser services:
Additionally, the client-side URoom and server-side Room may be subclassed, allowing each to implement their own custom behaviours and store their own custom data.
URoom objects are contained and created by NameSpace objects. Client-side NameSpaces typically "observe" their server-side counterparts so that URoom instance creation and removal is automatic (i.e., the NameSpace's list of URoom instances is automatically kept consistent with the actual Java Room instances on the server).
A URoom object should generally manage the data and implement the client-side logic for a room. In simple cases, a direct instance of URoom can handle an application's needs on its own. In more complex cases, custom features should be implemented in a URoom subclass. For example, a subclass might be a chat room ("ChatRoom") that handles messaging between clients and displaying a client list. A URoom subclass might also be a game room that implements the playing of a game ("TicTacToeRoom"). The display of a room's UI, however, is best handled outside of the URoom subclass (normally by a class that implements URoomListener and registers to receive URoom events via URoom.addURoomListener()). That is, URoom serves as the "model" of the Model/View/Controller architecture. See the client examples that ship with Unity for several examples of URoom subclasses.
When the Unity server starts, it automatically creates a special room called "unity" that can handle general server requests such as adding a new namespace or asking to join a room. The "unity" room is not meant to be joined directly. It merely acts as a global message receiver. The "unity" room is, hence, not represented by a client-side URoom instance.
Note that as of Unity 2, a client can be in more than one room at the same time.
theRoom.join([password])
Asks Unity to place the client in the server-side room represented by this URoom object.
The UPC generated by join() takes the form:
<UPC>
<ROOMID>unity</ROOMID>
<METH>joinRoom</METH>
<ARGS>
<ARG>roomID</ARG>
<ARG>namespace</ARG>
<ARG>password</ARG>
</ARGS>
</UPC>
In response to which, Unity sends the following response UPC to the client that asked to join the room:
<UPC>
<METH>upcOnJoinRoom</METH>
<ARGS>
<ARG>roomID</ARG>
<ARG>namespace</ARG>
<ARG>status</ARG>
<ARG>attrName1=attrVal1
[TAB_CHARACTER]
attrName2=attrVal2
[TAB_CHARACTER]
...
attrNamen=attrValn</ARG>
</ARGS>
</UPC>
where status is a message describing the results of the join attempt. Possible status values are:
status is anything other than ROOM_NOT_FOUND, the status codes shown above are made available via a URoomEvent passed to onJoin().
theRoom.leave()
Asks Unity to remove the client from the server-side room represented by this URoom object.
The UPC generated by leave() takes the form:
<UPC>
<ROOMID>unity</ROOMID>
<METH>leaveRoom</METH>
<ARGS>
<ARG>roomID</ARG>
<ARG>namespace</ARG>
</ARGS>
</UPC>
In response to which, Unity sends the following response UPC to the client that asked to leave the room:
<UPC>
<METH>upcOnLeaveRoom</METH>
<ARGS>
<ARG>roomID</ARG>
<ARG>namespace</ARG>
<ARG>status</ARG>
</ARGS>
</UPC>
where status is a message describing the results of the leave attempt. Possible status values are:
1.0.7