CSAR (Clustered Server Authoritative Ruler)
本ドキュメントは CSAR モジュール に関するドキュメントです。 CSAR モジュール は Diarkis ランタイム・ライブラリ と Diarkis-Module の上位レイヤーにあたり、Diarkis の低レイヤーの機能を組み合わせて一般的なゲームやアプリの実装モデルを想定した機能を提供し、より使いやすくしたライブラリです。
通信モデル
CSAR では通信モデルとしてホストクライアント型とメッシュ型をサポートしており、このどちらかもしくは混在させて使用することができます。
ホストクライアント型 (Single Authority)
オーソリティとなるホスト役が存在し、そのホスト役に対してクライアントが接続するタイプになります。クライアントはホスト役のみと送受信する事が可能で、ホスト役は全クライアントから受け取ったデータをもとにゲームサーバの処理を行い結果をクライアントに返すようなモデルを想定しています。Single Authority には、Client-Hosted タイプと DGS タイプがあります。DGS タイプは、ホスト役はクライアントではなく 専用ゲームサーバー（DGS サーバー）がオーソリティを担います。Client-Hosted タイプは、クライアントの中の１つがホスト役も担います。DGS タイプは、クライアントプログラムは CASR を通して Diarkis クラスタ内に配置したDGS サーバーに接続することができます。 Client-Hosted タイプでは、ネットワークに参加したコンピュータの中から CSAR が自動的にオーソリティとなるユーザーを指定します。
メッシュ型 (No Authority)
オーソリティとなるホスト役が存在せず、各クライアントが対等な関係で接続するタイプです。ネットワークに参加している各コンピュータがそれぞれ全員とデータの送受信をすることが可能です。
通信経路の抽象化
Diarkis ランタイム・ライブラリ には Room を使用したリレー通信、P2P 通信など様々な経路の通信方法が存在します。 クライアントライブラリを直接使用する場合、目的に応じてユーザーが API を使い分ける必要がありますが、CSAR では初期化時に使用したい通信経路を指定するとその経路の中で利用可能なものを使用してデータの送受信を行います。 たとえば初期化時に Room と P2P を有効にすると P2P を優先して使用しつつ、ホールパンチングに失敗したユーザーに対しては Room でデータを送信するといった動作をします。
CSAR に接続する流れ
CSAR に接続し、他のユーザーと通信を行うための手順について説明します。
初期化処理
ConnectionManager のインスタンスを作成します。ConnectionManager は CSAR の機能にアクセスするためのインターフェイスです。内部に DiarkisInterface をもっており、この機能を使用して CSAR の機能を提供します。DiarkisInterface は ConnectionManager の初期化時に外部から渡すインターフェイスもあり、ユーザーが作成したものを使用することも可能です。
Diarkis サーバへ接続
ConnectionManager::ConnectDiarkisServer で Diarkis サーバへ接続します。本 API の初期化時にコンフィグとして接続先のサーバのアドレスなどを設定します。接続処理の結果は DiarkisConnectionEvent で受け取ることができ ConnectionManager::AddServerConnectCallback で呼び出されるコールバックを設定することができます。
ゲームンスタンスの開始
Diarkis サーバへ接続完了後、ConnectionManager::StartGameInstance でゲームインスタンスを開始することができます。 ゲームインスタンスはデータの送受信を行うグループを表す概念で CSAR を使用して通信を行うユーザーは同じゲームインスタンスに参加する必要があります。 ゲームインスタンスはゲームインスタンス ID によって識別され、それぞれのユーザーが同じ ID に対して ConnectionManager::StartGameInstance を実行することにより同じゲームインスタンスに参加することができます。
ゲームインスタンス開始時にゲームインスタンスに関する様々な設定を行うことができます。
ConnectionMode
ゲームのタイプによって Authority となるホスト役が必要になるかで指定することができます。
Single Authority
Authority となるホスト役が存在し、そのホスト役で当たり判定などを行ってゲームが進行するタイプになります。Host-Cliented タイプや DGS タイプのゲームで利用頂けます。
No Authority
Authority となるホスト役が存在せず、各クライアントが対等な関係で接続するタイプです。格闘ゲームなどのゲームで利用を想定したモードになります。
Shared Authority
全クライアントで Authority を共有して、ホスト役とクライアント役を担います。 ※1
※1 : Shared Authority モードは、今後削除を予定しています。ご利用を予定されている場合ご相談ください。
NetworkType
以下の通信タイプから選択することができます。
Room & P2P
内部的に Room に入室して、 Room 経由の Relay 通信 と P2P を利用して通信します。P2P で通信できる時 P2P で通信し、P2P で通信できにないときは Room 経由で通信します。どの経路で通信しているか意識しないで使用することができます。
Room
内部的に Room に入室して、 Room 経由の Relay 通信のみを利用して通信します。
DGS
内部的に Room に入室して、別途起動している DGS サーバーに接続して通信します。DGS では、必ず ConnectionMode は Single Authority を選択して頂く必要があります。※2
OFFLINE
Diarkis サーバーに接続せず OFFLINE でゲームを動作させるためのモードになります。OFFLINE では、必ずConnectionMode は Single Authority を選択して頂く必要があります。
※2 : DGS を使用する際は、別途 アプリケーションを DGS サーバーで起動しておく必要があります。
MaxMembers
ゲームインスタンスに参加するクライアントの数を指定します。
ゲームインスタンス開始処理の結果は GameInstStartEvent で受け取ることができ ConnectionManager::AddGameInstStartCallback で呼び出されるコールバックを設定することができます。
ゲームインスタンス開始が成功すれば自分自身は CSAR への接続が完了した事になります。
また、ゲームインスタンスに参加した結果、自分がゲームのホスト役となった場合、ゲームサーバの処理の開始を要求する LaunchHostProcess イベントが発生します。 このイベントはゲームサーバの処理を新たに開始する必要がある、ゲームインスタンスの開始時と後述するホストマイグレーション時に発生します。 ユーザはこのイベントのコールバックをトリガーとしてゲームサーバの開始処理を行うことができます。 LaunchHostProcess イベントは ConnectionManager::AddLaunchHostProcessCallback で呼び出されるコールバックを設定することができます。
参加ユーザーの情報取得
ゲームインスタンスに自分以外のユーザーが接続すると UserConnect イベントが発生します。UserConnect イベントは ConnectionManager::AddUserConnectCallback で呼び出されるコールバックを設定することができます。 ゲームインスタンスから自分以外のユーザーが離脱すると UserDisconnect イベントが発生します。UserDisconnect イベントは ConnectionManager::AddUserDisconnectCallback で呼び出されるコールバックを設定することができます。 ゲームインスタンスに参加しているユーザーは ConnectionManager::GetConnectedClients もしくは ConnectionManager::GetConnectedUsers で取得することが可能です。詳細は API ドキュメントをご参照ください。
データの送受信
ホストクライアント型を使用している場合、データの送信にはホストクライアント型専用の SendToHost/SendToClient を使用します。この API で送信したデータは DataToHost/DataToClient イベントで受け取ることができ、ConnectionManager::AddDataToHost/AddDataToClient で呼び出されるコールバックを設定することができます。
メッシュ型を使用している場合、データの送信にはメッシュ型専用の SendBroadcast/SendMulticast/SendUnicast を使用します。この API で送信したデータは DataToUser イベントで受け取ることができ、ConnectionManager::AddDataToUserCallback で呼び出されるコールバックを設定することができます。
終了処理
ゲームインスタンスから離脱するには ConnectionManager::ExitFromGameInstance を使用します。 ゲームインスタンスから離脱すると ConnectionManager::ExitFromGameInstance を実行したユーザーは GameInstExit イベントで離脱したことを受け取ることができ、ConnectionManager::AddGameInstExitCallback で呼び出されるコールバックを設定することができます。 ホストクライアント型のクライアントを除くその他のユーザーは OnUserDisconnect を受け取ります。
ゲームインスタンスから離脱後、ConnectionManager::DisconnectDiarkisServer を使用して Diarkis サーバから切断します。
ホスト役かどうかの判断
ConnectionManager::IsHost で自身がホスト役になっているかどうかを確認することができます。
ホストマイグレーションのフロー
CSAR が Single Authority でかつ Host-Cliented タイプで動作している場合、ホスト役が退出したり不測の事態によりアプリがクラッシュするなどホスト役がネットワーク上に不在になると、CSAR は新たなホスト役を選任してホスト役を切り替える事(ホストマイグレーション) でゲームを継続しようとします。 ホストマイグレーションは以下のフローで実行されます。
ホストの状態の保存
ホストマイグレーションに備えて、ホスト役だけが持っているマスターデータの情報を CSAR 上に保存することが可能です。 ConnectionManager::StoreGameState を呼び出すことで任意のバイト列を 10 KiB まで保存することができます。
クライアントの場合
ホスト役が認識できなくなった場合、HostOffline イベントが発生します。 HostOffline 通知後、CSAR は 自動的に新たなホスト役に接続する処理を開始します。その後、新たなホスト役が決定し、通信の準備が完了すると HostMigrationComplete イベントが発生します。
HostOffline イベントは ConnectionManager::AddHostOfflineCallback で、HostMigrationComplete イベントは ConnectionManager::AddHostMigrationCompleteCallback でそれぞれ呼び出されるコールバックを設定することができます。
新しいホストの場合
新しくホスト役として選出された場合、クライアントの側のイベントに加えて LaunchHostProcess イベントが発生します。 このイベントでは新たにホスト役として選出されたことの通知とともに前任のホスト役が ConnectionManager::StoreGameState で保存したデータがあればそのデータを取得することが可能です。このデータをもとにアプリ側でホスト役の状態を復元することで、ホストが他のコンピュータに移動しても保存時の状態を復帰することできます。
その他の機能
ホストクライアント型とメッシュ型の共存
ゲームインスタンスをホストクライアント型で初期化後に ConnectionManager::AllowSendDataBetweenClients を使用することで同時にメッシュ型の通信を使用することができるようになります。 この機能はデフォルトでは無効になっており、明示的に有効化する必要があります。ゲームインスタンスが開始された後にConnectionManager::AllowSendDataBetweenClients を true で呼び出すと SendBroadcast, SendMulticast, SendUnicast を実行してクライアント間でデータをやり取りすることができるようになります。これらのデータはDataToUserCallback で受信することができます。また、ConnectionManager::GetConnectedUsers で他のクライアントの UID を取得することが可能になります。
最終更新
役に立ちましたか？