Utilize Room Module from Client

Introduction

This page describes the process of using the Room module via a C++ client runtime with the Diarkis Module. Before using the Room module, ensure that you are connected to the Diarkis server. Please refer to [the general flow of using the Diarkis Module](link to Diarkis モジュール利用の全体的な流れ) to establish a connection to the Diarkis server. The Room module can be used with both TCP and UDP protocols.

Basic Usage

Setting Up a Room in the Diarkis Module

First, call DiarkisInterfaceBase::SetupRoom() to set up a DiarkisRoomBase in the Diarkis Module. SetupRoom initializes the DiarkisRoomBase, configuring logging, event, and callbacks. Once the setup is complete, you can utilize various Room functionalities.

Creating a Room

You can create a Room on the server using DiarkisRoomBase::SendCreateRoom(). When creating a Room, you can specify parameters such as the maximum number of participants, whether to leave an empty Room, join the Room upon creation, the lifespan of the Room on the server, and data transmission intervals. For detailed information, please refer to the DiarkisRoomBase::SendCreateRoom() documentation.

When the Room creation is completed on the server, the event DiarkisRoomBase::OnRoomCreation() is triggered. Users can obtain the ID of the created Room from the event arguments. If you are using the Diarkis Module, this ID is saved internally and can be retrieved using methods like DiarkisRoomBase::GetRoomID().

Joining a Room

You can join a Room by specifying the Room ID with DiarkisRoomBase::SendJoinRoom(). The Room ID must be communicated to you through some form of communication such as DM from the user who created the Room. Additionally, there's a function to join any available Room randomly using DiarkisRoomBase::SendRandomJoinRoom(). This function creates a new Room if no joinable Room is available.

When a user joins a Room on the server, the event DiarkisRoomBase::OnRoomJoin() is triggered for the joining user, and DiarkisRoomBase::OnRoomMemberJoin() for existing Room members.

Sending Messages to Users in the Room

While in a Room, you can send data to other users using the following methods. The sent data is processed on the server and relayed to other users.

• DiarkisRoomBase::SendBroadcastToRoom()

  • Sends data to all users in the Room.

• DiarkisRoomBase::SendMessageToRoom()

  • Sends data to a specified user.

• DiarkisRoomBase::SendRelay()

  • Sends data to all users except yourself, prioritizing delivery speed from the server.

• DiarkisRoomBase::SendRelayTo()

  • Sends data to a specified user, similar to SendMessageTo but prioritizes delivery speed from the server.

When messages are received using these methods, the following events are triggered, allowing you to receive the data:

• DiarkisRoomBase::OnRoomMemberBroadcast()

  • Triggered upon receiving data sent via DiarkisRoomBase::SendBroadcastToRoom().

• DiarkisRoomBase::OnRoomMemberMessage()

  • Triggered upon receiving data sent via DiarkisRoomBase::SendMessageToRoom().

• DiarkisRoomBase::OnRoomRelay()

  • Triggered upon receiving data sent via DiarkisRoomBase::SendRelay().

• DiarkisRoomBase::OnRoomRelayTo()

  • Triggered upon receiving data sent via DiarkisRoomBase::SendRelayTo().

Leaving a Room

You can leave a Room you are currently participating in by executing DiarkisRoomBase::SendLeave(). When the leaving process is executed on the server, the event DiarkisRoomBase::OnRoomLeave() notifies you of the result. Additionally, the event DiarkisRoomBase::OnRoomMemberLeave() is triggered for remaining users to inform them of the user's departure. If the Room's owner changes as a result of the departure, the event DiarkisRoomBase::OnRoomOwnerChange() will be triggered.

Retrieving Room Information

You can query and retrieve information about the Room from the server.

Retrieving the Room Owner

You can query the current Room owner's ID by executing DiarkisRoomBase::SendGetOwnerID(). The result is notified through the event DiarkisRoomBase::OnRoomGetOwnerID(), and the result is stored within DiarkisRoomBase. The stored ID can be retrieved using DiarkisRoomBase::GetOwnerUID().

Retrieving Room Members

You can query the list of user IDs currently participating in the Room by executing DiarkisRoomBase::SendGetMemberIDs(). The result is notified through the event DiarkisRoomBase::OnRoomMemberIDs(), and the result is stored within DiarkisRoomBase. The list of stored user IDs can be retrieved using DiarkisRoomBase::GetRoomMembers().

Retrieving the Number of Room Members

You can query the number of users currently participating in the Room by executing DiarkisRoomBase::SendGetNumberOfMembers(). The result is notified through the event DiarkisRoomBase::OnRoomNumberOfMembers().

Sharing Information in the Room

You can share data among users participating in a Room by utilizing the Room on the server.

Sharing Data Using Properties

Coming Soon

Sharing Data Using Objects

Coming Soon

Exchanging Messages within the Room

Coming Soon

Special Features

Establishing P2P Connections Among Room Participants

Users within a Room can establish P2P connections with each other. The P2P connection process is initiated when a user in the Room calls DiarkisRoomBase::SendStartP2PSync(). The server will send a list of connection addresses to users in the Room upon receiving this request. On the client side, DiarkisRoomBase::OnStartP2PSync() is triggered, signaling that the notification has been received and the hole-punch process can begin with the provided list of connection addresses. Once hole-punching is complete, direct communication between peers becomes possible.

Reserving a Room

Coming Soon

Searching for a Room

Coming Soon

Migrating a Room

If a migration occurs while using a Room, a Room-specific migration process 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 Diarkis server hosting the Room scales in, all members in the Room must reconnect to the server and move to the same Room. The migration process executes automatically with a simple call to migrate by the Room's owner.

For more details on migration, refer to Migration.

When migration occurs while in a Room, DiarkisRoomBase::OnOffline() is called instead of DiarkisTcpBase/DiarkisUdpBase::OnOffline(), indicating the server scale-in and the need for Room migration.

In the SDK's sample code, it is implemented as follows:

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

    // Due to server scale-in, the server hosting the Room goes offline.
    // According to the app's implementation, call SendMigrateRoom at the appropriate timing to move the Room (server).
    if (GetOwnUID() == GetOwnerUID())
    {
        // The Room's owner should call Migrate
        this->SendMigrateRoom();
    }
}

Note that, as mentioned in the sample comment, only the Room owner needs to call DiarkisRoomBase::SendMigrateRoom(). Also, similar to DiarkisTcpBase/DiarkisUdpBase, a temporary disconnection from the Room occurs after the call, so adjust the timing of calling DiarkisRoomBase::SendMigrateRoom() according to the app's requirements.