Utilizing Room Module from Client

Introduction

This page explains the procedure for using the Room module through the C++ client runtime with the Diarkis Module. Before using the Room module, it is essential to establish a connection to the Diarkis server. Please refer to [the overall procedure for utilizing the Diarkis Module] (link to the full procedure for using the Diarkis Module) to connect to the Diarkis server. The Room module can be used with either TCP or UDP.

Basic Usage

Setting Up the Room with the Diarkis Module

First, call DiarkisInterfaceBase::SetupRoom() to set up DiarkisRoomBase of the Diarkis Module. SetupRoom initializes DiarkisRoomBase and sets up logging and event callbacks. Once the setup is complete, various Room functionalities become available.

Creating a Room

You can create a Room on the server using DiarkisRoomBase::SendCreateRoom(). When creating a Room, you can specify the number of participants, whether to leave an empty Room, whether to join the Room upon creation, the survival time of the Room on the server, the data transmission interval, etc. For details, refer to the documentation of DiarkisRoomBase::SendCreateRoom().

Also, when the Room creation is completed on the server, it is notified as an event through DiarkisRoomBase::OnRoomCreation(). The user can obtain the ID of the created Room from the argument of this event. When using the Diarkis Module, this ID is internally saved and can be obtained using methods like DiarkisRoomBase::GetRoomID().

Joining a Room

You can join a Room by specifying a Room ID with DiarkisRoomBase::SendJoinRoom(). The Room ID should be communicated by the user who created the Room, for example, via direct messages. Additionally, there is a feature to join a randomly available Room using DiarkisRoomBase::SendRandomJoinRoom(). If no rooms are available, a new Room will be created.

When a user joins a Room on the server, DiarkisRoomBase::OnRoomJoin() is notified to the joining user, and DiarkisRoomBase::OnRoomMemberJoin() is notified to users already in the Room.

Sending Messages to Users in the Room

While in a Room, you can send arbitrary data to other users using the following methods. The transmitted data is processed on the server and delivered to other users from the server.

• DiarkisRoomBase::SendBroadcastToRoom()

  • Sends data to all users in the Room.

• DiarkisRoomBase::SendMessageToRoom()

  • Sends data only to the user specified as an argument.

• DiarkisRoomBase::SendRelay()

  • Sends data to users other than yourself in the Room, attempting to deliver it as quickly as possible from the server, unlike BroadcastToRoom.

• DiarkisRoomBase::SendRelayTo()

  • Sends data only to the user specified as the argument but aims to deliver it as quickly as possible from the server, unlike MessageTo.

When receiving messages sent using these methods, the following events will occur, allowing you to receive the data.

• DiarkisRoomBase::OnRoomMemberBroadcast()

  • Event for receiving data sent through DiarkisRoomBase::SendBroadcastToRoom()

• DiarkisRoomBase::OnRoomMemberMessage()

  • Event for receiving data sent through DiarkisRoomBase::SendMessageToRoom()

• DiarkisRoomBase::OnRoomRelay()

  • Event for receiving data sent through DiarkisRoomBase::SendRelay()

• DiarkisRoomBase::OnRoomRelayTo()

  • Event for receiving data sent through DiarkisRoomBase::SendRelayTo()

Leaving a Room

You can leave the Room you are currently participating in by executing DiarkisRoomBase::SendLeave(). Once the leave process is executed on the server, the DiarkisRoomBase::OnRoomLeave() event fires to notify the result of the process. Meanwhile, other users will be notified of the leave by firing DiarkisRoomBase::OnRoomMemberLeave(). If the owner of the Room changes as a result of the leave, DiarkisRoomBase::OnRoomOwnerChange() will fire.

Obtaining Room Information

You can query the server to obtain information about the Room.

Obtaining the Room Owner

By executing DiarkisRoomBase::SendGetOwnerID(), you can query the server for the current Room owner's ID. The result of the query is notified by firing DiarkisRoomBase::OnRoomGetOwnerID() and the result is stored inside DiarkisRoomBase. The stored ID can be obtained with DiarkisRoomBase::GetOwnerUID().

Obtaining Room Members

By executing DiarkisRoomBase::SendGetMemberIDs(), you can query the server for a list of user IDs currently participating in the Room. The result of the query is notified by firing DiarkisRoomBase::OnRoomMemberIDs() and the result is stored inside DiarkisRoomBase. The stored user ID list can be obtained with DiarkisRoomBase::GetRoomMembers().

Obtaining the Number of Room Members

By executing DiarkisRoomBase::SendGetNumberOfMembers(), you can query the server for the number of users currently participating in the Room. The result of the query is notified by firing DiarkisRoomBase::OnRoomNumberOfMembers().

Sharing Information in the Room

You can use the server's Room to share data among users participating in the Room.

Sharing Data with Properties

Coming Soon

Sharing Data with Objects

Coming Soon

Exchanging Messages within the Room

Coming Soon

Special Features

Establishing P2P Connections Among Room Participants

Users participating in a Room can establish P2P connections. By calling DiarkisRoomBase::SendStartP2PSync() for users participating in the Room, the P2P connection process will begin. The server receiving this request sends a list of connection addresses to the participating users in the Room. On the client side, DiarkisRoomBase::OnStartP2PSync() fires to receive this notification, starting the hole punching process against the sent list of connection addresses. Once hole punching is complete, direct communication with the connected peers becomes possible.

Reserving a Room

Coming Soon

Searching for a Room

Coming Soon

Room Migration

When a migration occurs while using a Room, dedicated migration processing for the Room must be executed.

Due to the characteristics of the Room module, members participating in the same Room are connected to the same server. If the server on which the Room is created scales in, reconnection of all members of the server participating in the Room and migration to the same Room will be necessary. The migration processing is automatically executed by simply calling migrate as the Room owner.

For details on migration, refer to Migration.

If migration occurs while participating in a Room, instead of calling OnOffline() in DiarkisTcpBase/DiarkisUdpBase, DiarkisRoomBase::OnOffline() will be called, indicating the necessity of server scale-in and room migration processing.

In the sample code provided with the SDK, it is implemented as follows:

void DiarkisRoom::OnOffline()
{
    DiarkisRoomBase::OnOffline();

    // Due to server scale-in, the server with the Room where you are in becomes offline.
    // Please call SendMigrateRoom at an appropriate timing according to the implementation on the app-side to move the Room (server).
    if (GetOwnUID() == GetOwnerUID())
    {
        // The Room owner calls Migrate
        this->SendMigrateRoom();
    }

}

However, for Room, as noted in the sample comment, only the Room owner needs to call DiarkisRoomBase::SendMigrateRoom(). Also, similar to DiarkisTcpBase/DiarkisUdpBase, after calling, there will be a temporary disconnection from the Room, so adjust the timing for calling DiarkisRoomBase::SendMigrateRoom() according to the convenience of the app.

For a detailed flow including the server side, refer to the following API documentation.

https://docs.diarkis.io/docs/server/v1.0.0/diarkis/room/index.html#MigrateRoom