オンラインセッション

概要

Quamtumのオンラインサービスは、Photon共通のオンラインインフラストラクチャ（Photon Realtime）上に構築されています。オンラインセッションへの接続は、通常は3つの接続フェーズを経て行われます。

1. カスタム認証：Photonはプレイヤーアカウントを提供しないため、独自またはサードパーティー製の認証プロバイダーを使用して安全にログインし、Photonのカスタム認証を行うことを推奨します。
2. ゲームサーバー接続：オンラインシミュレーションを開始する前に、クライアントはPhoton Cloudに接続し、Photon Realtime APIを使用してPhotonのルームに参加する必要があります。
3. Quantumシミュレーション開始シーケンス：このフェーズでQuantumシミュレーションの開始・同期を行い、クライアント設定とプレイヤーデータを送信します。

ゲームサーバー接続

Photon Cloudへの接続を確立し、ゲームサーバーへマッチメイキングするための最も簡単な方法は次の通りです。

C#

var connectionArguments = new MatchmakingArguments {
    // アプリケーションの情報を含むPhotonAppSettingsです。
    PhotonSettings = PhotonServerSettings.Global.AppSettings,
    // Photon Cloudに設定するようにリクエストするプラグインです。
    PluginName = "QuantumPlugin"
    // 明示的にルーム名を指定すると、CanOnlyJoinの設定に基づいてルームの作成/参加が試みられます。RoomNameをnullにすると、ルーム作成時にユニークな名前が付きます。
    RoomName = "My Room Name",
    // ルームに接続できる最大クライアント数で、大抵のケースでは、Quantumシミュレーションの最大プレイヤー数と同じになります。
    MaxPlayers = Input.MAX_COUNT,
    // 参加のみを試みるか？ルーム作成もリクエストするか？を設定します。
    CanOnlyJoin = false,
    // カスタム認証に置き換えたら、ここで明示的にAuthValuesを設定します。
    UserId = Guid.NewGuid().ToString(),
};

// Photon Cloudに接続し、引数に基づいてマッチメイキングを行い、最終的にルームへ参加します。
RealtimeClient Client = await MatchmakingExtensions.ConnectToRoomAsync(connectionArguments);

実践的には、ConnectToRoomAsync()/ReconnectToRoomAsync()をTry Catchで囲んでください。または、他のTaskに例外を投げてください。

C#

var client = default(RealtimeClient);
try {
    client = await MatchmakingExtensions.ConnectToRoomAsync(connectionArguments);
} catch (Exception e) {
    // 何か予期せぬことが発生した場合、
    // 詳細なエラー処理を行う必要はまず無いので、一般的なフィードバックとしてログを表示し、再試行を促します。
    Debug.LogException(e);
}

ConnectToRoomAsync()中に投げられる例外の例は次の通りです。

• Failed to connect and join with error 'X'：Photon Cloud接続がエラーで失敗した場合
• MaxPlayer must be greater or equal than 0
• MaxPlayer must be less than 256
• PhotonSettings must be set
• TaskCanceledException：AsyncConfig.CancellationTokenでキャンセルがリクエストされた場合

ReconnectToRoomAsync()中に投げられる例外の例は次の通りです。

• AppVersion mismatch：ReconnectInformation.AppVersionがPhotonSettings.AppVersionと異なる場合
• UserId not set：ReconnectInformation.UserIdがnullか空の場合
• UserId mismatch：ReconnectInformationとAuthValuesのUserIdが異なる場合
• ReconnectInformation timed out：ReconnectInformationが古い場合
• ReconnectInformation missing：ReconnectInformationがnullの場合

AppSettings

Photon Cloudに接続するためには、AppSettingsと呼ばれる設定が必要です。Unityプロジェクトでは、PhotonServerSettings.Instance.AppSettingsからグローバルアセットにアクセスできます。

設定オブジェクトは常にコピーするようにして、UnityエディターのPhotonServerSettingsアセットへ変更が保存されないようにしてください。

C#

var appSettings = new AppSettings(PhotonServerSettings.Global.AppSettings);

Photon AppIdのセットアップについては、Quantum Asteroids チュートリアル - プロジェクトの準備をご覧ください。

MatchmakingArgumentsのオプション

MatchmakingArgumentsでは、以下のようなオプション引数が利用できます。

詳細はPhoton Realtimeのマッチメイキングガイドをご覧ください。

Quantumシミュレーション開始シーケンス

以下のスニペットは、Quantumのオンラインセッションを開始する基本的な操作を示します。

C#

var sessionRunnerArguments = new SessionRunner.Arguments {
    // RunnerFactoryによって、Quantum.RunnerとUnityを結合します
    RunnerFactory = QuantumRunnerUnityFactory.DefaultFactory,
    // デフォルトのQuantumGameStartParametersを作成します
    GameParameters = QuantumRunnerUnityFactory.CreateGameParameters,
    // 実行中のセッションへ再接続するためのプレイヤースロットを確保する際に使用される秘密のユーザーIDです
    ClientId = Client.UserId,
    // プレイヤーのデータです
    RuntimeConfig = runtimeConfig,
    // QuantumDefaultGlobalでタグ付けされたUnityアセットからロードされるセッション設定です
    SessionConfig = QuantumDeterministicSessionConfigAsset.DefaultConfig,
    // オンラインセッションのGameModeはMultiplayerにする必要があります
    GameMode = DeterministicGameMode.Multiplayer,
    // セッションの最大プレイヤー数です。ここでは、コード生成されたQuantumシミュレーションの最大プレイヤー数を使用します。
    PlayerCount = Input.MAX_COUNT,
    // 接続ロジックとQuantumプロトコルが失敗するタイムアウト時間です
    StartGameTimeoutInSeconds = 10,
    // Communicatorは、シミュレーション開始後にネットワーク処理を引き継ぎます
    Communicator = new QuantumNetworkCommunicator(Client),
};

// クライアントがオンラインセッションへ正常に参加するとメソッドが完了します
QuantumRunner runner = (QuantumRunner)await SessionRunner.StartAsync(sessionRunnerArguments);

プレイヤーの追加/削除

Quantumにはプレイヤーの概念があります。各クライアントは0～複数のプレイヤーを持つことができます。Quantumオンラインセッションを開始してからプレイヤーを明示的に追加するまで、クライアントは観客の状態になります。

ゲームに接続している各プレイヤーには、ユニークIDが割り当てられます。このIDはPlayerRefと呼ばれ、Playerとして参照されます。

Quantum 2.1とは異なり、プレイヤーはいつでも追加/削除できます。

プレイヤーが占有するPlayerSlotsは、クライアントが自身のプレイヤーを管理するために参照されます。ローカルプレイヤースロットが1つのみ使用される場合、そのスロットは0になります。クライアントが2番目のプレイヤーを制御する場合は、PlayerSlotが1になります。典型的な使用例は、入力コールバックCallbackPollInputで、どのローカルプレイヤー入力をポーリングするかを制御する際（QuantumGame.AddPlayer(Int32 playerSlot, RuntimePlayer data)）にPlayerSlotプロパティを使用します。

AddPlayer()は、開発者のバックエンドへHTTPリクエストを送信する可能性があるため、サーバー側に操作頻度の制限があり、スパムできないようになっています。

RuntimePlayer

Quantumにはプレイヤーオブジェクト/プレイヤーアバターの概念は組み込まれていません。

プレイヤーに関連するゲーム情報（キャラクターの装備・レベルなど）は、各クライアントがRuntimePlayerオブジェクトを使用してシミュレーションに渡すことになります。

C#

// プレイヤースロット0にプレイヤーを追加する
QuantumRunner.Default.Game.AddPlayer(runtimePlayer);

プレイヤースロットを明確に指定するには、QuantumGame.AddPlayer(int playerSlot, RuntimePlayer data)を以下の例のように使用します。

C#

// プレイヤースロット1にプレイヤーを追加する
QuantumRunner.Default.Game.AddPlayer(1, runtimePlayer);

PlayerConnectedSystem

Quantumセッションへのプレイヤー接続を追跡するために、入力と接続フラグが使用されます。PlayerConnectedSystemはこのプロセスを自動化し、プレイヤーのセッションへの接続/切断をシミュレーションに通知します。

接続/切断のコールバックを受け取るには、システムにISignalOnPlayerConnected/ISignalOnPlayerDisconnectedを実装する必要があります。

ローカルプレイヤーの便利なコールバック

ローカルプレイヤー処理に便利なコールバックとして、CallbackLocalPlayerAddConfirmed・CallbackLocalPlayerRemoveConfirmed・CallbackLocalPlayerAddFailed・CallbackLocalPlayerRemoveFailedがあります。

C#

QuantumCallback.Subscribe(this, (CallbackLocalPlayerAddConfirmed c)    => OnLocalPlayerAddConfirmed(c));
QuantumCallback.Subscribe(this, (CallbackLocalPlayerRemoveConfirmed c) => OnLocalPlayerRemoveConfirmed(c));
QuantumCallback.Subscribe(this, (CallbackLocalPlayerAddFailed c)       => OnLocalPlayerAddFailed(c));
QuantumCallback.Subscribe(this, (CallbackLocalPlayerRemoveFailed c)    => OnLocalPlayerRemoveFailed(c));

セッションの停止/切断

Quantumシミュレーションを停止するには、QuantumRunner.ShutdownAll(bool immediate)を実行します。Quantumコールバック内で呼び出されていない場合のみ、immediate:trueが設定できます。ShutdownコマンドがQuantumコールバック内で呼び出されている場合は、immediate:falseの設定が必須で、次のUnity更新までシャットダウンが延期されます。

ShutdownAllはQuantumRunnerオブジェクトを破棄し、Quantumローカルシミュレーションの停止がトリガーされます。StartParameters.QuitBehaviourの設定値によって、Disconnect()/LeaveRoom()のいずれかが実行されます。

クライアントがゲームを正常に終了する（例：プレイヤーアバターを後片付けする）場合は、シミュレーションで追加のロジックを実装する必要があります。これには、クライアントが発行したコマンドか、プレイヤー接続状態（PlayerConnectedSystemを参照）の監視を行います。

プレイヤーがアプリを閉じたり、ゲームを「Alt+F4」で終了したりすることを考慮すると、正常に切断できる機会が常にあるとは限りません。

C#

async void Disconnect() {
    // すべてのランナーをシャットダウンし、切断するまで待機する
    await QuantumRunner.ShutdownAllAsync();

    // または、単純にシャットダウンする
    QuantumRunner.ShutdownAll();
}

プラグイン切断エラー

クライアント開始プロトコルや入力メッセージでQuantumプラグインにエラーが発生した場合、接続を正常に終了する命令が送信されます。その場合、クライアント上でCallbackPluginDisconnectコールバックが呼び出され、詳細を含むReason文字列が取得できます。これらのエラーは復帰不可能のため、クライアントは再接続とシミュレーションの再起動が必要です。