Using the Room Module from the Client

Introduction

This page explains the process of using the Room module via the Diarkis Module from a C++ client runtime. Before using the Room module, ensure that you are connected to the Diarkis server. Refer to the Overall Flow for Using the Diarkis Module to connect to the Diarkis server. The Room module can be used over either TCP or UDP.

Basic Usage

Setting Up the Room with the Diarkis Module

First, call DiarkisInterfaceBase::SetupRoom() to set up DiarkisRoomBase within the Diarkis Module. SetupRoom initializes DiarkisRoomBase, configures logging, and sets up event callbacks. Once set up, 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 parameters such as maximum number of participants, whether to leave an empty Room, whether to join the Room immediately upon creation, the Room's lifetime on the server, and data transmission intervals. Refer to the documentation for DiarkisRoomBase::SendCreateRoom() for details.

Additionally, once the Room is successfully created on the server, DiarkisRoomBase::OnRoomCreation() will notify you via an event. Users can obtain the created Room's ID from this event’s arguments. When using the Diarkis Module, this ID is stored internally and can be retrieved using methods like DiarkisRoomBase::GetRoomID().

Joining a Room

You can join a Room by specifying the Room ID in DiarkisRoomBase::SendJoinRoom(). The Room ID must be communicated to you by the user who created the Room via DM or other methods. You can also use DiarkisRoomBase::SendRandomJoinRoom() to join an available Room at random. If no Room is available, a new Room will be created.

When a user joins a Room on the server, DiarkisRoomBase::OnRoomJoin() notifies the joining user, and DiarkisRoomBase::OnRoomMemberJoin() notifies existing users 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 data is processed on the server and then forwarded to other users.

• DiarkisRoomBase::SendBroadcastToRoom()

  • Sends data to all users in the Room.

• DiarkisRoomBase::SendMessageToRoom()

  • Sends data only to the user specified in the argument.

• DiarkisRoomBase::SendRelay()

  • Sends data to all users in the Room except yourself, but unlike BroadcastToRoom, the server sends the data as quickly as possible.

• DiarkisRoomBase::SendRelayTo()

  • Sends data only to the user specified in the argument, but unlike MessageTo, the server sends the data as quickly as possible.

When a message sent using these methods is received, the following events will be triggered, allowing you to handle the received data.

• DiarkisRoomBase::OnRoomMemberBroadcast()

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

• DiarkisRoomBase::OnRoomMemberMessage()

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

• DiarkisRoomBase::OnRoomRelay()

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

• DiarkisRoomBase::OnRoomRelayTo()

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

Leaving a Room

You can leave the current Room by executing DiarkisRoomBase::SendLeave(). When the leave process is executed on the server, the DiarkisRoomBase::OnRoomLeave() event will fire, notifying you of the result. Other users in the Room will be notified that a user has left via the DiarkisRoomBase::OnRoomMemberLeave() event. If the owner of the Room changes as a result of leaving, the DiarkisRoomBase::OnRoomOwnerChange() event will fire.

Retrieving Room Information

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

Retrieving the Room Owner

You can query the server for the current Room owner ID by executing DiarkisRoomBase::SendGetOwnerID(). The result of the query will be notified by the DiarkisRoomBase::OnRoomGetOwnerID() event and the result is stored within DiarkisRoomBase. The stored ID can be retrieved using DiarkisRoomBase::GetOwnerUID().

Retrieving Room Member IDs

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

Retrieving Number of Room Members

You can query the server for the current number of users in the Room by executing DiarkisRoomBase::SendGetNumberOfMembers(). The result of the query will be notified by the DiarkisRoomBase::OnRoomNumberOfMembers() event.

Sharing Information in the Room

Using the server's Room, data can be shared 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 in the Room can establish P2P connections with each other. By calling DiarkisRoomBase::SendStartP2PSync(), users participating in the Room can initiate the P2P connection process. The server will send a list of connection addresses to the participating users. On the client side, DiarkisRoomBase::OnStartP2PSync() will fire, notifying you to start the hole-punching process with the received connection addresses. Once hole-punching is complete, direct communication between peers is possible.

Reserving a Room

Coming Soon

Searching for a Room

Coming Soon

Room Migration

When a migration occurs while using a Room, special migration processing exclusive to the Room must be executed.

Given the nature of the Room module, all members participating in the same Room are connected to the same server. If the Diarkis server hosting the Room undergoes a scale-in, all members will need to reconnect to the server and move to the same Room. The Room owner can trigger the migration by calling Migrate, which automatically handles the migration process.

For more details on migration, refer to Migration.

When a migration occurs while participating in a Room, DiarkisRoomBase::OnOffline() is called instead of DiarkisTcpBase/DiarkisUdpBase::OnOffline(), notifying you that server scale-in is necessary and that Room migration processing is required.

The following implementation is provided in the sample code included with the SDK:

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

    // Due to server scale-in, the server hosting the Room will go offline.
    // Based on your application's implementation, call SendMigrateRoom at the appropriate timing to move the Room (server).
    if (GetOwnUID() == GetOwnerUID())
    {
        // The Room owner calls Migrate
        this->SendMigrateRoom();
    }

}

However, in the case of a Room, as indicated in the sample comments, only the owner needs to call DiarkisRoomBase::SendMigrateRoom(). Additionally, similar to DiarkisTcpBase/DiarkisUdpBase, after the call, you will be temporarily disconnected from the Room, so adjust the timing of calling DiarkisRoomBase::SendMigrateRoom() according to your application’s needs.