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:
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.
最終更新