Basic Concepts | Unity Realtime

The Gamedonia Realtime solution allows clients to stay connected to a central server via a persistent connection (using the TCP protocol or similar). The server is responsible for maintaing the game state and synchronizing players with each other.

To understand how the synchronization between players happens, you should first get familiar with some of the basic concepts.

In Gamedonia RT, users need to join rooms to be able to interact with each other. Let's see how this process is done:

Basic usage flow

Your first step should be to connect to the Gamedonia servers. If you haven't done it yet, check our Get Started guide first.

Login

Once there exists an active connection, you can log a user in. This is done by sending a Login operation> to the server.

	GamedoniaRT gdRt = GamedoniaRT.SharedInstance ();
	LoginOperation lop = new LoginOperation ();
	lop.name = this.nickname;

	gdRt.SendOp (lop);

And we can register for Login return events like this:

	gdRt.AddEventListener (GamedoniaEvents.ON_LOGIN_SUCCESS, OnLoginSuccess);
	gdRt.AddEventListener (GamedoniaEvents.ON_LOGIN_ERROR, OnLoginError);

Check if a room exists

If everything went fine, the user is now logged in but still outside of any room.

Before the user can join a room, we need to check if it exists (in this example, we will search for DefaultRoom). If it does, we will join it. If it doesn't, we will create it and join it afterwards. Let's see how we can search for a room:

	GamedoniaRT gdRt = GamedoniaRT.SharedInstance ();
	Room room = gdRt.roomsManager.GetRoomByName ("DefaultRoom");

	if (room == null) {
	   //Create room
	} else {
	   //Join room       
	}

Gamedonia RT SDK stores a local representation of the visible Rooms and User information of the game. You can access all room information through the rooms manager exposeed in the GamedoniaRT singleton.

Create a Room

If the room we want to join didn't exist yet, we need to create it. This operation is a bit more complex because it requires the specification of the Settings of the room we want to create.

The CreateRoom operation is invoked like this:

	GamedoniaRT gdRt = GamedoniaRT.SharedInstance ();
	RoomSettings rs = new RoomSettings ();
	CreateRoomOperation crop = null;

	rs.name = "DefaultRoom";
	rs.isGame = false;
	rs.maxUsers = 100;
	rs.removePolicy = Room.REMOVE_POLICY_NEVER;                
	crop = new CreateRoomOperation (rs);
	gdRt.SendOp (crop);

And we can register for the CreateRoom return events like this:

	GamedoniaRT gdRt = GamedoniaRT.SharedInstance ();
	gdRt.AddEventListener (GamedoniaEvents.ON_CREATE_ROOM_SUCCESS, OnCreateRoomSuccess);
	gdRt.AddEventListener (GamedoniaEvents.ON_CREATE_ROOM_ERROR, OnCreateRoomError);

To get more information about the room settings and the CreateRoom operation, check the Operations guide.

Join Room

Once we are sure a room exists, users can start joining it. If there is still place for another user, he will be able to become part of the room. A user can be a member multiple rooms.

To make a user join a room, send the following operation:

	GamedoniaRT gdRt = GamedoniaRT.SharedInstance ();
	JoinRoomOperation jrop = new JoinRoomOperation ("DefaultRoom");
	gdRt.SendOp (jrop);

We can register for JoinRoom return events like this:

	GamedoniaRT gdRt = GamedoniaRT.SharedInstance ();
	gdRt.AddEventListener (GamedoniaEvents.ON_JOIN_ROOM_SUCCESS, OnJoinRoomSuccess);
	gdRt.AddEventListener (GamedoniaEvents.ON_JOIN_ROOM_ERROR, OnJoinRoomError);

Set variables

Now that we have joined at least one room, we start exchanging information with other users in the room.

Gamedonia Realtime uses the exchange of variables to share information between users in a room.

There are 2 types of variables:

  • Room variables: They are stored in the room. All changes to this variables will be broadcasted to the users connected to this room.
  • User variables: They are stored in the user. Changes to these variables are sent to any user linked in any way to the user. For instance, all concurrent users in a room will see updates to the other user variables (if the variable is declared as shared).

The choice between user and room variables will depend on the game we are developing. If by design a game allows a player to be connected to a single room, then it is better user vars to exchange information between users, as they are a bit easier to handle.

This is an example on how to send a user variable to the server:

	List<Gamedonia.Rt.Entities.UserVariable> userVariables = new List<Gamedonia.Rt.Entities.UserVariable>();
	userVariables.Add(new Gamedonia.Rt.Entities.UserVariable("x", 1.1));
	userVariables.Add(new Gamedonia.Rt.Entities.UserVariable("y", 1.653));
	userVariables.Add(new Gamedonia.Rt.Entities.UserVariable("z", 1.2332));
	userVariables.Add(new Gamedonia.Rt.Entities.UserVariable("rot", 0.68));
	SetUserVariablesOperation suvop = new SetUserVariablesOperation(userVariables,gdRt.me);

And this is how you should register to the corresponding events:

	GamedoniaRT gdRt = GamedoniaRT.SharedInstance ();
	gdRt.eventsDispatcher.AddEventListener (GamedoniaEvents.ON_SET_USER_VARIABLES_SUCCESS, OnSetUserVariablesSuccess);
	gdRt.eventsDispatcher.AddEventListener (GamedoniaEvents.ON_SET_USER_VARIABLES_ERROR, OnSetUserVariablesSuccess);

GamedoniaRT Singleton

This singleton class will be the main node of communication between the client and the real-time server. All functionalities of the real-time solution are exposed through this class.

Methods

  • Connect() - It's used to start a connection against the Gamedonia Realtime servers.
  • Disconnect() - Closes an open connection against the Gamedonia Realtime servers.
  • SendOp() - Used to send information from the client to the server.
  • AddEventListener() - Allos you to register for callback events coming from the server.

Connect and Disconnect also send an operation to the server, but we exposed these two methods directly for simplicity.

Local Managers

The GamedoniaRT class also gives you access to a local representation of the users and rooms structure that exists on the server. To access this local representation you have two specific managers available:

  • RoomManager - Handles the representation of the rooms structure on the server side. The visibility of the rooms will depend on the permissions and groups.
  • UsersManager - Handles the representation of the users connected in some way to the currently logged in user.

Other Properties

The me property contains a representation of the current client connected to the server.

Event Callbacks

Communication between the server and the client is bidirectional, so the client will receive event callbacks from the server in response to operations generated by itself or from other other clients in the same room.

We have seen examples on how to add listeners for events, now we will see how to define a corresponding callback method. For instance, the callback for the User Joined Room event would look like this:

	void OnUserJoinedRoom(Gamedonia.Rt.Events.Event evt) {

	   //Process the event

	}

The method name has to be the same as the one we registered in the AddEventListener call. The only diffence in the signature of the method for each callback is the content of the Gamedonia.Rt.Events.Event parameter received. Each event type has a different content inside the Gamedonia Event parameter.

Gamedonia.Rt.Events.Event has the following properties:

  • type - Specifies the type of event generated. It's very important to know what information is stored inside each field.
  • data - Stores information related to the response from the server. We need to know the eventy type to extract the data correctly.

Custom Types

Gamedonia Realtime allows you to exchange information between the client and the server. The information types allowed include the basic ones, like int, long, double, string, etc. You can also add custom complex types which are combinations of simple or other complex types.

In he SDK you will find the following types:

  • Gamedonia.Rt.Types.Map - It's a special Map type where you can store key/value pairs that can be sent to the server.
  • Gamedonia.Rt.Types.Array - A custom array type to store other simple or Gamedonia Map/Array complex types.

Both types include specific Put / Get methods to access stored data inside them. It's very important to know the type you are retrieving because if the types library cannot convert the specified type automatically then you will get a null value even if the object contains the specified key.

For example, let's say you have stored a user inside a Gamedonia Map using the PutUser method. See what would happen if you try to recover it:

	User user = …. // A user we retrived from another source :)

	// Add the user to the Map
	Gamedonia.Rt.Types.Map data = new Gamedonia.Rt.Types.Map();
	data.PutUser("myuser",user);

	// Recover the key using an incorrect type.
	Room mistake = data.GetRoom("myuser");
	// the variable mistake is null because a user cannot be cast to a Room type.

	// Now recover to the right type
	User myuser = data.GetUser("myuser");

	// Great, now we have the user!