The Room module allows you to have multiple remote clients join and share a virtually created room to exchange messages freely. Room module can also be used as an RPC broker for remote clients to exchange RPC commands using its broadcast and messaging.
Setting Up Room Module
The Room module is network protocol agnostic, but it needs to have a network client passed to it.
We will explain how to set up a room module instance with Diarkis TCP or UDP client.
Setting Up With Diarkis UDP Client
Diarkis.Udp udp = new Diarkis.Udp();
Diarkis.Modules.Room room = new Diarkis.Modules.Room();
// This is how you pass a UDP client instance
room.SetupAsUdp(udp);Setting Up With Diarkis TCP Client
Diarkis.Tcp tcp = new Diarkis.Tcp();
Diarkis.Modules.Room room = new Diarkis.Modules.Room();
// This is how you pass a TCP client instance
room.SetupAsTcp(tcp);How To Create A Room
With the Room module, you may create rooms with a fixed number of allowed members with optional settings for the room. OnCreate is raised when you invoke this method. If a UDP client is used, the message is sent as a RUDP.
// Maximum number of members for this room
int maxMembers = 10;
// If true, the room will not be discard when it is empty
bool allowEmpty = false;
// If true, the creator will automatically join the room created
bool join = true;
// TTL of the room in seconds when it is empty (this is only effective when allowEmpty=true)
int ttl = 60;
// Broadcast message buffering interval in milliseconds to lessen server stress
int interval = 200;
room.OnCreate += HandleOnRoomCreate;
// Creates a new room and raises OnCreate event
room.Create(maxMembers, allowEmpty, join, ttl, interval);
private void HandleOnRoomCreate(bool success, string roomID, uint createdTime)
{
// success = false means we failed to create a new room
// createdTime is the timestamp of the room creation
}How To Join A Room
To join a room, you need the room ID of the room. You will probably need to store the room IDs externally or use Match Maker to share room IDs. Also, we recommend your message include the sender’s user ID and other necessary information so that the recipients may detect who has joined and behave accordingly. When you join a room, OnJoin will be raised. Other members’ clients of the room will raise OnMemberJoin. If a UDP client is used, the message is sent as a RUDP.
byte[] message = Encoding.UTF8.GetBytes("Hello World");
// This message will be sent to the other members when you join the room successfully. Other members will receive the message via OnMemberJoin event
room.Join(roomID, message);Detecting A New Member
When a new member joins a room, the OnMemberJoin event is raised. Below is an example of how to handle the event:
room.OnMemberJoin += HandleRoomOnMemberJoin;
private void HandleOnRoomMemberJoin(byte[] message)
{
// message is the message byte array that the new member sent with room.Join()
}How To Leave A Room
Leaving a room will raise OnLeave and the other members’ clients will raise OnMemberLeave if the leave was successful. We recommend your message include the sender’s ID and other necessary information so that the recipients may detect which member has left the room and behave accordingly. If a UDP client is used, the message is sent as a RUDP.
byte[] message = Encoding.UTF8.GetBytes("Bye World");
// This message will be sent to the other members when you leave the room successfully. Other members will receive the message via OnMemberLeave event
room.Leave(room.GetRoomID(), message);Detecting A Member Leaving
When a member leaves the room, the OnMemberLeave event is raised. Below is an example of how to handle the event:
room.OnMemberLeave += HandleRoomOnMemberLeave;
private void HandleRoomOnRoomMemberLeave(byte[] message)
{
// message is the byte array the member left sent with room.Leave()
}Join A Random Room Or Create A New Room If No Room Is Available
If you simply want to have your client join or create a room randomly, use this method. The event raised by the method is the same: OnJoin/OnMemberJoin or OnCreate. If a UDP client is used, the message is sent as a RUDP.
// Maximum number of members for this room
int maxMembers = 10;
// TTL of the room in seconds when it is empty (this is only effective when allowEmpty=true)
int ttl = 60;
// This message will be sent to the other members when you join the room successfully. Other members will receive the message via OnMemberJoin event
byte[] message = Encoding.UTF8.GetBytes("Hello World");
// Broadcast message buffering interval in milliseconds to lessen server stress
int interval = 200;
room.JoinRandom(maxMembers, ttl, message, interval);How To Broadcast A Message To All Members Of Room
The broadcast method will send a message to all members of the room including yourself. The message will be received by OnMemberBroadcast. We recommend your message includes the sender’s user ID and other information so that the recipients may detect who has sent the message and behave accordingly.
byte[] message = Encoding.UTF8.GetBytes("Hello World");
// For UDP, if set to true, broadcast message will be sent as an RUDP packet
bool reliable = false;
room.BroadcastTo(room.GetRoomID(), message, reliable);How To Receive Broadcast Messages
When other members send broadcast messages, the OnMemberBroadcast event is raised. Below is an example of how to handle the event:
room.OnMemberBroadcast += HandleOnRoomMemberBroadcast;
private voidd HandleOnRoomMemberBroadcast(byte[] message)
{
// Do something great with the message
}How To Send A Message To Selected Members Of Room
You may send a message to selected members of the room instead of all members. The message will be delivered by OnMemberMessage. We recommend your message includes the sender’s user ID and other information so that the recipients may detect who has sent the message and behave accordingly.
// For UDP, if set to true, broadcast message will be sent as an RUDP packet
byte[] message = Encoding.UTF8.GetBytes("Hellow World");
bool reliable = false;
room.MessageTo(room.GetRoomID(), message, reliable);How To Get Properties Of A Room
You may retrieve properties of the room you are in by providing property names. To read the retrieved properties, you must listen to OnGetProperties. All properties are byte arrays. If a UDP client is used, the message is sent as a RUDP.
List<string> propertyNames = new List<string>();
propertyNames.Add("roomName");
propertyNames.Add("roomNo");
room.GetProperties(room.GetRoomID(), propertyNames);How To Update Properties Of A Room
You may update the properties of the room you are in. All property values MUST be byte arrays.Calling UpdateProperties will raise OnUpdateProperties. If a UDP client is used, the message is sent as a RUDP.
Dictionary<string, byte[]> props = new Dictionary<string, byte[]>();
props["roomName"] = Encoding.UTF8.GetBytes("Sample Room");
props["roomNo"] = BitConverter.GetBytes(123);
room.UpdateProperties(room.GetRoomID(), props);How To Synchronize A Numeric Room Property
By using room property, you may share and synchronize numeric room properties.
The examples below will explain how to manage and synchronize a numeric room property with members of your room.
How To Set Up Synchronization Of A Numeric Room Property Changes
The example below explains how to set up an event listener to synchronize the numeric room property value with all members of the room.
// This event is raised when a numeric room property value changes
room.OnIncrPropertySync += OnDiarkisRoomIncrPropertySync;
private void OnDiarkisRoomIncrPropertySync(long value)
{
// Update UI and do some cool things here
}How To Initialize A Numeric Room Property
Typically the user client that creates the room initializes the numeric room property.
// We do not need to synchronize with other members assuming there is nobody yet
bool sync = false;
// This initializes a numeric room property named HP and its value will be 1000
room.IncrProperty("HP", 1000, sync)How To Update A Numeric Room Property And Synchronize
You may increment or decrement a numeric room property and auto-synchronize with the other members of the room.
// This event is raised when the update is synchronized from another member
room.OnIncrPropertySync += OnDiarkisRoomIncrPropertySync;
private void OnDiarkisRoomIncrPropertySync(long updatedValue)
{
// Update UI and do something awesome
}
// This is how you update a numeric room property
// This will be subtracting HP by 100
// synchronize = true means auto-synchronization with other members
bool synchronize = true;
room.IncrProperty("HP", -100, synchronize);How To Synchronize A Numeric Room Property As A New Member
When a new member joins the room, the new member client needs to retrieve the current value of the numeric room property.
// We retrieve "HP" after we join a room
room.OnJoin += OnDiarkisRoomJoin;
private void OnDiarkisRoomJoin(bool success, uint createdTime)
{
if (!success)
{
// Handle error...
return;
}
// Retrieve "HP"
List<string> propertyNames = new List<string>();
propertyNames.Add("HP");
// This raises OnGetProperties event and that is how you retrieve the property data
room.GetProperties(room.GetRoomID(), propertyNames);
}
// This is how to retrieve "HP" from the server
room.OnGetProperties += OnDiarkisRoomGetProperties;
private void OnDiarkisRoomGetProperties(bool success, Dictionary<string, byte[]>properties)
{
if (!success)
{
// Handle error...
return;
}
if (!properties.ContaionsKey("HP"))
{
// "HP" is missing...
return;
}
// Update local "HP"
Array.Reverse(properties["HP"]); // Big Endian
_hp = BitConverter.ToInt64(msg.Value, 0);
}How To Obtain Other Members’ IDs and The Owner’s ID
You may retrieve a list of member IDs along with the owner ID.
room.OnGetMemberIDs += OnDiarkisRoomGetMemberIDs;
private void OnDiarkisRoomGetMemberIDs(bool success, string ownerID, string[] memberIDs)
{
// Do something great here!
}
// This will raise OnGetMemberIDs event
room.GetMemberIDs();Conclusion
The concept of Room is one of the most fundamental concepts of real-time appplications.
Diarkis Room module is extremely flexible and can be adapted to perform various operations making it more than the basic function of real-time appplications.