PlayFab Party オブジェクトとその関係
PlayFab Party API のパワーと柔軟性をうまく活用するには、その範囲で定義されている次の不可欠なオブジェクトについてまず理解する必要があります。
- デバイス - 物理デバイスで実行しているゲームの別個のインスタンス。 API が使用されている場合は、必ずローカル デバイスが存在します。
-
ユーザー - ログオンしている別個のプレイヤー、より厳密には、ゲームが認証または識別目的で PlayFab パーティーに提供する PlayFab
title_player_accountエンティティ。 指定されたデバイスには 1 人以上のユーザーが関連付けられています。 - ネットワーク - 1 つ以上のデバイスとその承認されたユーザーのセキュリティで保護されたコレクション。チャットやデータ通信をやりとりするためにゲームが作成します。 ネットワークは通常、ゲームのマルチプレイヤー セッションまたはチャット パーティーの概念に合わせて調整されます。
- エンドポイント - ネットワーク内でデータを送受信するための抽象化。 エンドポイントは、デバイス、ユーザー、または希望するゲーム固有のコンセプトを表す場合があります。
- チャット コントロール - 1 つ以上のネットワークでボイス チャットまたはテキスト チャットを構成、発信または対象とするためのユーザーの表現。
オブジェクトの関係性
単純化された概念階層として、ネットワークにはデバイスが含まれ、これにユーザーと、オプションのエンドポイントとチャット コントロールが含まれます。 例:
上記の関係性の図はわかりやすいものの、PlayFab Party の機能を描写するには実際には不完全であり、そのまま捉えると誤解につながるおそれがあります。 実際には、Party API は同時に複数のネットワークに接続しているデバイスをサポートしています。 たとえば、ユーザーがフレンドのグループとのコミュニケーションを長期間にわたって維持したいと考えていますが、その同じグループが、見知らぬユーザーを含む別々のより大きなゲーム セッションの参加や退出をしているとします。 このより広範囲なシナリオを考慮すると、これらのオブジェクトの関係性をよりよく理解できます。
直感的には、デバイスがネットワークに所属していると考えられるかもしれませんが、これは正しくありません。 デバイスがネットワークに参加しているというのがより正確な捉え方です。 そのため、特定のインスタンスが検出されたとき、ローカル デバイスと共有しているネットワークの数に関係なく、Party ライブラリが作成するのはリモートおよびローカルのどちらかに関係なく 1 つのデバイス API プロジェクトだけです。
たとえば、次の図では、2 つのネットワークと、ユーザー、チャット コントロール、エンドポイントを含む 3 つのデバイスが示されています。 デバイス A およびその 2 つのチャット コントロール (および関連付けられているユーザー) はネットワーク 1 に参加していますが、デバイス B および C は共にネットワーク 1 およびネットワーク 2 に接続されており、それぞれに 1 つのチャット コントロール (および関連付けられているユーザー) があります。 すべてのデバイスは、接続している各ネットワークに 1 つか 2 つのエンドポイントを作成しています。
この図では、3 つのデバイスには共通のネットワークが 1 つ以上存在するため、それぞれのデバイスは 3 つのデバイスすべての 1 つのインスタンスと、そのチャット コントロールを確認できます。 デバイス A はネットワーク 1 でエンドポイント 1 〜 4 についてしか知りませんが、デバイス B および C はネットワーク 2 で作成したエンドポイント 5 〜 7 も確認できます。
デバイス C が両方のネットワークではなくネットワーク 2 にのみ参加する場合、次のようになります。
- 当然、デバイス C はネットワーク 1 でエンドポイント 4 を作成することも、エンドポイント 1 - 3 を参照することもできません。
- デバイス C は、ネットワーク 1 だけに存在するデバイス A やその 2 つのチャット コントロールについて知りません。
- 同様に、デバイス A にはネットワーク 2 だけに存在するデバイス C が表示されません。
ただし、デバイス B は両方のネットワークに存在するため、すべてのデバイスおよびそのチャット コントロールを引き続き確認できます。
そのため、デバイスおよびチャット コントロールはネットワークとの厳格な階層的なツリーの関係性の "外" にありますが、ゲーム インスタンスが付属するネットワークのコンテキストなしに、リモート デバイスまたはチャット コントロールに実際に遭遇することはないことに注意しておくことは重要です。 ローカルおよびリモート デバイス、またはチャット コントロールに 1 つ以上の共通のネットワークが存在する場合、リモート オブジェクトを確認できる可能性があります。 ただし、共通のネットワークがない場合、リモート オブジェクトが作成されることはありません。
注意
PlayFab パーティーを正常に使用するために、ゲームが複数のネットワークに同時に接続することは必須ではありません。 複数のネットワークを使用するかどうか、およびその方法の詳細については、後続の高度なトピックを参照してください。
一般的なオブジェクト属性
すべてのオブジェクトには、明確に定義された有効期間があります。 ローカル ゲーム インスタンスは、直接的に、またはゲームが選択する期間中にのみ通知される標準化された通知メカニズムを使用して、各オブジェクトを作成および破棄します。 通知を使用した作業については、後ほどのトピックで詳しく説明します。
すべての PlayFab Party API オブジェクトは、カスタム コンテキストの概念もサポートしています。これは単純に、オプションの、ローカルのみの "ショートカット" ポインターまたは値をオブジェクトと一緒に保存する方法です。 カスタム コンテキストにより、効率の悪いルックアップを実行することなく、PlayFab パーティー オブジェクトから対応するプライベート ゲーム オブジェクトに簡単に移動できます。 ポインター値はローカル ゲーム インスタンスでしか意味をなさないため、これらの値はリモートでは送信されません。
最後に、ネットワークを除く上記のすべてのオブジェクトには、特殊な "ローカル" のサブオブジェクトがあります。これには、オブジェクトを所有するローカル デバイスだけが使用できる方法およびプロパティがあります。
たとえば、ローカルまたはリモートのエンドポイントを代表するために使用されるベースの PartyEndpoint オブジェクトと、そのエンドポイントが実際にローカル デバイスによって作成された場合にのみ PartyEndpoint::GetLocal() を介して受信できる、より具体的な PartyLocalEndpoint オブジェクトがあります。 1 つのデバイスが異なるリモート デバイスのソース エンドポイントからデータを何らかの方法で送信できることは理にかなっていないため、ここで、ゲーム データを送信するための PartyLocalEndpoint::SendMessage() メソッドが公開されます。
C++ PlayFab Party インターフェイス (推奨) を使用する場合、オブジェクトは C++ クラス インスタンスとして公開されます。 フラット C インターフェイスを使用する場合、オブジェクトはハンドルの値によって代表されます。
すべての主要オブジェクトの詳細
-
マネージャー (
PartyManager) -
ネットワーク (
PartyNetwork) -
デバイス (
PartyDeviceおよびPartyLocalDevice) -
ユーザー (ユーザー エンティティ ID および
PartyLocalUser) -
エンドポイント (
PartyEndpointおよびPartyLocalEndpoint) -
チャット コントロール (
PartyChatControlおよびPartyLocalChatControl) -
状態の変化 (
PartyStateChange)
マネージャー
前述したオブジェクトに加えて、PlayFab Party API はトップレベルの PartyManager シングルトン オブジェクトも公開します。
ユーティリティ/組織オブジェクトは、主に他のオブジェクトの作業を開始するための出発点として使用されます。 マネージャーでは、新しいネットワークおよびローカル ユーザーなどが作成されます。 すべての非同期的操作の完了と通知もここで一元化されています。 最も基本的には、マネージャーは、PlayFab パーティー ライブラリ自体が使用前に初期化され、必要なくなった場合にクリーンアップされる場所です。
ネットワーク
PartyNetwork オブジェクトは、参加デバイスのセキュリティで保護されたデバイス、承認されたユーザー、および付属するエンドポイントまたはチャット コントロールを代表します。
ネットワークは、最初は空の状態で作成されますが、デバイスが接続して 1 人以上のユーザーをネットワーク内へ認証します。
認証されているユーザーを持たないネットワークは、タイムアウト期間の後に自動的に破棄されます。
接続には、ネットワーク記述子を使用してネットワークが参照されます。 ネットワーク記述子 は主に、PlayFab パーティーがネットワークを識別して見つけるために内部で必要になる情報を含む、非透過的なバイナリ構造です。 また、API は構造と Web サービスに適した文字列をシリアル化するためのメソッドを提供することで、共通のソーシャル プラットフォームの招待メカニズムである PlayFab マッチメイキングや、PlayFab Party 自体のスコープ外の他の外部のランデブー メカニズムを使用して、他のデバイスと交換できるようにしています。
注意
まれな状況で、ネットワークのネットワーク記述子が変更される場合があります。 追加のデバイス接続に関する問題を回避するため、ゲームはそのような変更の通知に備え、既存のネットワークのネットワーク記述子を更新または再公開する必要があります。
ネットワーク記述子がある場合でも、ネットワークへのアクセスは承認されたユーザーに制限されます。 このユーザー認証は、ネットワークの作成時に、および招待の作成と失効の繰り返しを通して行われます。これについては、「招待とセキュリティ モデル」のトピックで詳しく説明します。
ゲームは招待を使用して、参加をユーザーのフレンドのみに制限したり、悪意のあるプレイヤーがネットワークに参加するのを防ぐことができます。
デバイスは同時に 1 つ以上のネットワークに接続できます。 複数のネットワークを使用するかどうか、およびその方法の詳細については、後ほどのトピックを参照してください。
PartyNetwork オブジェクトに対して実行できる操作の種類には、ローカル ユーザーの認証、チャット コントロールの接続と列挙、エンドポイントの作成と列挙、およびネットワークのパフォーマンスに関する広範な情報の取得が含まれます。
デバイス
PartyDevice オブジェクトは、ゲームの異なるインスタンスと、物理デバイスで実行している PlayFab Party ライブラリ コードを代表します。
ほとんどの操作は PartyDevice オブジェクト自体で実行されるのではなく、どのエンドポイントまたはチャット コントロールがそのゲーム インスタンス (特に複数のユーザーを同時にサポートするプラットフォームおよびゲーム) に所属するかを定義するための組織的なメカニズムです。
PlayFab Party はこの関係性の知識を活用して、ゲーム データとチャットの送信を最適化します。たとえば、デバイス上の複数の対象ユーザーが受け取る必要がある場合でも、メッセージのコピーを 1 つ送信します。
リモートの PartyDevice オブジェクトは、ネットワーク接続とユーザーの認証による副生成物です。
デバイスに関連付けられている有効かつ認証されたリモート ユーザーが、ローカル デバイスが接続しているのと同じネットワークに参加している場合にのみ作成されます。 同様に、この条件に該当しなくなった場合にも破棄されます。
一方、PartyLocalDevice に特化したサブオブジェクトは、PlayFab Party が初期化されている限り、ローカル ゲーム インスタンスがいつでも利用して参照できます。
明示的に作成または破棄されることはありません。
ユーザー
PlayFab パーティー ユーザーは、ゲームがtitle_player_accountエンティティ ID およびトークンを取得するために PlayFab プレイヤー ログインを実行する一意の人間のプレイヤーです。
リモート ユーザーは、PlayFab Party API でチャット コントロールおよびオプションでエンドポイントと関連付けられているエンティティ ID のみによって識別されます。 専用のオブジェクトを使用して表されることはありません。 これは、生の識別のため、およびそれらの他のオブジェクトと関連付けられているラベルとしての機能以外に、任意のユーザーと有意義に対話する機能が PlayFab Party に備わっていないためです。
一方、ゲームは PlayFab Party 内の有効期間の管理を所有しているため、ローカル ユーザーには明示的な PartyLocalUser オブジェクトがあります。
通常、PlayFab プレイヤーが適用可能なログイン方法を使用したことをゲームが正常にログすると、ゲームは PartyLocalUser を作成し、そのユーザーがログオフすると、必要に応じて PartyLocalUser を破棄します。
複数のローカル プレイヤーがログインしている状態をサポートするプラットフォームおよびゲームでは、各プレイヤーに対して追加の PartyLocalUser オブジェクトを作成する必要があります。
PartyLocalUser オブジェクトもまた、すべての認証の基礎であるため重要です。 新しいネットワークを作成したり、ネットワークへの認証を実行するには、有効なローカル ユーザーが存在する必要があります。
ユーザーの認証については、招待とセキュリティ モデルを扱ったトピックで詳しく説明します。
PartyLocalUser オブジェクト自体に行われる操作はごく少数ですが、ほとんどすべての操作で、PartyLocalUser が提供されるか存在している必要があります。
PartyLocalUser オブジェクトは PartyManager オブジェクトを使用して作成されます。
作成者だけが明示的に破棄できます。
リモート デバイスで直接的なオブジェクト代表はありませんが、所有デバイスが PartyLocalUser を削除したり、適切な方法かどうかに関係なくネットワークから切断したりすると、それに関連付けられているチャット コントロールおよびエンドポイントは破棄されます。
エンドポイント
PartyEndpoint オブジェクトはオプションですが、PlayFab Party のデータ通信を利用するゲームのコア部分です。
一般的なネットワーク ソケットと同様、エンドポイントは、ネットワーク内でデータ メッセージを発信または対象とするための抽象化されたアドレス指定メカニズムです。
メッセージの送受信のために一意に識別するデバイス、個々のユーザー、または任意のゲーム定義のコンセプト (タンク ユニットなど) を代表する場合があります。
専用の PartyLocalEndpoint サブオブジェクトは、ローカル ゲーム インスタンスによってネットワーク内で作成されたエンドポイント用です。
エンドポイントのほとんどの機能はここにあります。
その PartyLocalEndpoint::SendMessage() は、PartyLocalEndpoint から同じネットワーク内にある 1 つ以上の他の PartyEndpoint オブジェクトにゲーム データ ペイロードを送信します。
インターネットのパケット損失を処理し、低い方の帯域幅を使用するために、短い待機時間と同じまたは他のローカル エンドポイントからの複数のメッセージの連結の間のトレードオフを制御し、接続品質がゲームの送信するレートをサポートするのに十分ではない場合に対処するための最善の方法を選択するのに役立つさまざまなオプションを提供しています。
エンドポイントを使用したゲーム データの送信の詳細については、後ほどのトピックを参照してください。
データ メッセージ自体のソースまたは送信先となることに加え、各 PartyEndpoint オブジェクトには、ネットワーク内にある別々の PartyEndpoint オブジェクトに、またはそのオブジェクトから送信されたメッセージ ペイロードで特定のエンドポイントを参照できる 16 ビットのエンドポイントの一意の識別子が PlayFab Party によって割り当てられています。
これにより、完全でより大きなユーザー エンティティ ID の文字列またはそれが代表する他の識別子を送信するオーバーヘッドを回避する便利な方法が提供されます。自分のピアツーピアの識別合意交渉を構築する必要はありません。
PartyLocalEndpoint オブジェクトは、それに含まれる PartyNetwork オブジェクトを使用して作成されます。
これを行うと、対応する PartyEndpoint オブジェクトがリモート デバイスでも作成されます。
エンドポイントはその作成者が明示的に破棄することができます。または、所有デバイスがネットワークから切断するか、(指定されている場合は) 関連付けられている PartyLocalUser オブジェクトがネットワークから削除されると暗黙的に破棄されます。
チャット コントロール
PartyChatControl オブジェクトは、PlayFab Party のオプションであるチャット通信機能を使用するためのメカニズムです。
これは、特定のユーザーに関連付けられているオーディオ入力/出力デバイス、設定、通信ポリシーを代表します。
ローカル ゲーム インスタンスによって作成されたチャット コントロールでは、専用の PartyLocalChatControl サブオブジェクトも使用できます。
ここで、リモート PartyChatControl オブジェクトに、またはオブジェクトからのチャット通信を許可するアクセス許可を構成します。たとえば、ネットワーク全体のチャットかチーム専用チャットかを選択したり、プラットフォームのポリシー制限を適用したりします。
ローカルのチャット コントロールは、チャット テキストの送信、テキストの音声への合成、ボイス ストリームの文字起こし、翻訳、ミュートなどに使用されます。
PartyLocalChatControl オブジェクトは同じネットワーク内のリモート デバイスで PartyChatControl オブジェクトとして作成される前に、ネットワークに接続している必要があります。
デバイスおよびチャット コントロールが 1 つ以上の共通するネットワークに接続されている場合でも、デバイスには代表する 1 つの PartyChatControl オブジェクトが作成されたことだけが表示されます。
これは、不必要な複製や、音声およびチャット メッセージの中断を回避するのに役立ちます。
PartyLocalChatControl オブジェクトは、それに含まれる PartyLocalDevice オブジェクトを使用して作成されます。
チャット コントロールはその作成者が明示的に破棄することができます。または、所有デバイスがネットワークから切断するか、関連付けられている PartyLocalUser オブジェクトがネットワークから削除されると暗黙的に破棄されます。
状態の変化
PartyStateChange 構造は、非同期の操作の完了、受信メッセージ、更新通知、その他の API 関連のイベントをゲームに知らせるために使用されます。
インターネット上の複数のマシン間の予測不能なタイミングでの複雑な操作を行う方法を簡略化するため、PlayFab Party は、ゲームによる明示的な呼び出しの結果である場合を除き、API から報告するいかなる状態も変更しないことを保証しています。
ただし、リモートで開始された操作や、ローカル状態を変更する予期しない発生について知る方法は必要なため、PlayFab Party およびゲームは PartyManager::StartProcessingStateChanges() および PartyManager::FinishProcessingStateChanges() というメソッドの特別な組み合わせを通して連携します。
これらは、ゲームの作業ループにおいてそのような更新を処理するのに都合の良いタイミングで呼び出されます。
これらの新しいイベントは、0 個以上の PartyManager::StartProcessingStateChanges() 構造の配列として PartyStateChange から報告されます。
ゲームが状態の変化を処理したら、配列は PartyManager::FinishProcessingStateChanges() を使用して返されます。
PartyStateChange 構造は単独では完全なオブジェクトではありません。 完了または通知の特定の種類、該当するオブジェクトへのポインター、エラー情報に関する情報を含む、より詳細な構造にキャストされるベース ヘッダーです。
状態の変化の作業については、後ほどのトピックで詳しく説明します。