Migrating from Unity 1.x to Unity 2 Multiuser Server

What's the difference?

The concepts of Unity remain the same from Unity 1 to Unity 2 Multiuser Server (U2MS). Objects are deployed as virtual "Rooms" and are notified by U2MS of events. Functionality is added by reacting to those events in a meaningful way. The big difference in concept is that instead of directly subclassing the org.moock.unity.core.Room class "Rooms" instead implement the RoomListener interface. However, for the purposes of discussion they will still be called Rooms even though at the base level a Room is really a combination of an internal Room Object and the deployed RoomListener Object.

See this for a more detailed discussion of how the server works with Rooms.

The other major change is that U2MS is built to work very well with a communication protocol called Unity Procedure Call. It's very similar to the protocol used in all of the Unity 1 examples and is basically a very simple remote method invocation protocol. You can choose to not use UPC however that comes at the cost of having to write code to tell the server how to rout incoming messages received by the server to the appropriate room (since Clients can now be in more than one Room simultaneously) as well as not being able to take advantage of many of the built in features of Unity 2 Multiuser Server (eg. built in shared attribute notification).

You can read more about UPC here.

Making the Change

Step 1

public class MyGameRoom extends Room {

public class MyGameRoom implements RoomListener {

Step 2


    private RoomServices m_roomServices; // RoomServices for this Room

    public void onRoomInit(RoomServices roomServices) {

        // --- save the RoomServices reference

        m_roomServices = roomServices;

        // rest of your code goes here

    }

Unity 1.x to Unity 2 Multiuser Server Method Conversion Chart

Detailed information on using all Services can be found here. The chart is only a subset covering old 1.x functionality.

The chart assumes that methods invoked on the calling Room use a preset RoomServices reference m_roomServices (see Step 2 above).

Unity 1.x	Unity 2 Multiuser Server
killClient(Client client)	Services.getClientServices(String clientID).killClient()
killClient(int clientID)	Services.getClientServices(String clientID).killClient()
killRoom()	m_roomServices.killRoom()
killRoom(String roomID)	Services.getRoomManagementServices.killRoom(String roomID)
isDying()	m_roomServices.isDying()
getNumClients()	m_roomServices.getNumClients()
getNumClients(String roomID)	Services.getRoomServices(roomID).getNumClients()
broadcastRoom(*)	m_roomServices.broadcastRoom(String message)
broadcastRoomButClient(*)	m_roomServices.broadcastRoomButClient(String clientID, String message)
broadcastClient(*)	Services.getClientServices().broadcastClient(String message)
pauseRoom(long pause)	Deleted. Rooms are responsible for setting up their own additional threads. See this tutorial for an example.
getRoom(String roomID)	Services.getRoomServices(String roomID)
getRoomID()	m_roomServices.getRoomID()
getSentryID()	Deleted. Unity 2.x no longer uses Room Sentries for authentication.
getClientList()	m_roomServices.getClientList()
getClientListButClient(Client butClient)	Deleted. Use m_roomServices.getClientList() and simply remove the clientID(s) not wanted.
changeRoom(*)	Deleted. Use Services.getClientServices(clientID).leaveRoom(oldRoomID) and Services.getClientServices(clientID).joinRoom(newRoomID)
broadcastRoom(String roomid, String message)	Services.getRoomServices(roomID).broadcastRoom(String message)
getRoomNames()	Services.getRoomManagementServices.getRoomList()
getMaxClients()	m_RoomServices.getRoomProperties().getMaxClients()
getProperty(String name)	m_RoomServices.getAttribute(String name)
setProperty(String name, String value)	m_RoomServices.setAttribute(String name, String value)
spawnRoom(RoomProperties props)	Services.getRoomManagementServices().spawnRoom(RoomDefinition def)

Changing from Unity 1 style to UPC

Unity 1 had a completely open ended messaging structure. In other words, the server didn't need to know anything about the format of the incoming messages. This is contrary to U2MS where the server needs to know, via a MessageRouter, how to determine the destination Room for inbound Messages. However, in most examples we used a loose Message format based on XML snippets. If you built your Unity 1 app based on these examples then changing to UPC will be easy.

A typical Unity 1 XML snippet Message would look like:

<MESSAGE TYPE="broadcastText" FROM="client">
    <TEXT>Hi There!</TEXT>
</MESSAGE>

It contains all of the parts of a UPC Message. It has a Method, or Type, broadcastText, and it contains arguments, in this case 1 argument the Text to send or "Hi There!"

As a UPCMessage this would look like:

<UPC>
  <ROOMID>chatRoom05</ROOMID>
  <METH>broadcastText</METH>
  <ARGS>
    <ARG>Hi There!</ARG>
  </ARGS>
</UPC>

UPC is both more structured and more generic. U2MS also comes with Classes that allow you to quickly build and parse UPC as well as treat a UPC Message as an Object. For example to create this Message in Java you would use the following code:

UPCMessage upcMessage = new UPCMessage("broadcastText");
upcMessage.setRoomID("chatRoom05");
upcMessage.addArg("Hi There!");

For more details on working with UPC look here.