NameSpace Class

Constructor

Arguments

fullNsID

The fully qualified namespace id. For example, "moockapps.chat.sports".

roomFactory

A reference to the room factory instance used to create rooms in this namespace. Must be a URoomFactory instance or a URoomFactory subclass instance.

client

A reference to the UClient instance that contains this NameSpace.

Methods

Description

Instances of the NameSpace class store URoom instances, much the way directories on an operating system store files. You can use namespaces to run multiple Unity applications on the same server instance. For example, a chat application could create rooms in the "chat" namespace, and a chess game could create rooms in the "chess" namespace.

Do not use the NameSpace constructor to create NameSpace instances manually. Namespace instances are created automatically by the application's RoomManager and always correspond to an actual namespace on the server. To create a namespace on the server at runtime, use RoomManager.createNamespaceOnServer().

You can use UClient.joinRoom() to join a room on the server even when the corresponding NameSpace and URoom objects do not yet exist on the client. When the room is joined, the required NameSpace object(s) and URoom object will be created automatically. To respond to the creation of the new NameSpace instance(s), override UClient.onAddNamespace(). (For example you might want to add a listener to the NameSpace when it is created). You can also use RoomManager.addRoomManagerListener() to register any object to receive NameSpace addition and removal notifications, providing that the object implements RoomManagerListener .

When the Unity server starts, it automatically creates a namespace called "udefault", which acts as a general purpose place to put rooms for simple applications. The "udefault" namespace can be referred to as: "udefault", "null", or "" (the empty string). To receive notification of room additions and removals for "udefault", observe the namespace, as follows:

yourUClientSubClass.getRoomManager().observeNamespace("udefault")

NameSpace.removeRoom() Method

Synopsis

Arguments

roomID

The simple identifier of the room to remove. E.g., "chat" not "moockapps.chat".

Description

WARNING: This method is required only to explicitly remove URoom instances from a NameSpace. If the NameSpace in question is being observed, URoom instances are removed automatically, and this method is not required.

When a namespace is not observed, the Unity server does not send notification when rooms are added to or removed from the namespace. However, a room that exists on the server can still be joined via UClient.joinRoom() (provided that the client knows the fully qualified identifier of the room). When a room in a non-observed namespace is joined, the corresponding client-side NameSpace object is automatically created, along with a URoom object representing the joined room. However, if that room is removed from the server, the client will not be notified, so the URoom instance will never be deleted. In this situation, the client-side application is expected to delete the room manually, via NameSpace.removeRoom().

For example, suppose a tic tac toe application creates a namespace named "utictactoe.games", but does not observe it. Each tic tac toe game occurs in a room in "utictactoe.games". For example, "utictactoe.games.23vs10" would be a game room for client 23 playing client 10. If clients actually observed the namespace "utictactoe.games", each client would maintain a list of game room objects for every active game room on the server. If hundreds or thousands of games were being played, each client could be bogged down by the overhead of maintaining hundreds or thousands of room objects. To avoid this possible load, clients do not observe the namespace "utictactoe.games" because they are not interested in every game being played--they are interested only in game rooms that they are actually playing in. Each time a room is created in "utictactoe.games", only the client that created the room is notified (via RoomManagerListener.onCreateRoomResults). That client then tells its opponent to join the new room. When the game is finished, both clients leave the room, and the room is removed from the server. However, because the namespace "utictactoe.games" is not observed, neither client is told by the server to delete the corresponding client-side URoom object! Hence, each tic tac toe client must use NameSpace.removeRoom() to manually remove a game room when leaving it. If the client does not manually remove each game room it leaves, a URoom object for each game played will continue to exist until the client disconnects. If the client plays thousands of games, it will eventually be bogged down by orphaned game room objects.

Here's the code showing the onLeave() method of a tic tac toe game room listener (TicTacToeRoomView):

  public function onLeave (e:URoomEvent):Void {
    // Stop listening for room events.
    room.removeURoomListener(this);
    room.removeTicTacToeRoomListener(this);

    // We're not observing this
    // namespace, so we have to remove the room manually.
    room.getNamespace().removeRoom(room.getRoomID());

    // Get rid of the tic tac toe board.
    this.removeMovieClip();
  }

Note that NameSpace.removeRoom() is only required when a namespace is not being observed, in which case, the responsibility of removing rooms is left to the developer. When a namespace is observed, URoom objects are removed automatically when rooms are removed from the server. Furthermore, a namespace should generally be observed unless it is expected to create a very large number of rooms. For example, even in our tic tac toe scenario, the "utictactoe.games" namespace could safely be observed with as many as two or three hundred rooms in it. Only when performance is actually a concern in your applications should you consider not observing a namespace, and manually removing rooms.

Curious developers may be interested to know that NameSpace.removeRoom() is used internally by uClientCore to remove rooms from a namespace when the server reports that a room has been removed. The UPC used by Unity to announce a removed room is:

<UPC>
  <METH>upcNSRoomRemoved</METH>
  <ARGS>
    <ARG>namespaceID</ARG>
    <ARG>roomID</ARG>
  </ARGS>
</UPC>

Documentation Version

1.0.4