PlayFab パーティオブジェクトとそのリレーションシップ

PlayFab パーティー API の power と柔軟性の使い方は、スコープで定義されている次の重要なオブジェクトを理解することから始まります。

  • デバイス-物理デバイスで実行されているゲームの個別のインスタンス。 API を使用しているときは常にローカルデバイスが存在します。
  • ユーザー -個別のログイン状態のプレーヤー。または、より正確にtitle_player_account言うと、このゲームでは、認証と識別のために、再生されていた playfab パーティによってアクティブに提供されています。 Entity 1人以上のユーザーが特定のデバイスに関連付けられている。
  • ネットワーク-1 つ以上のデバイスと、チャットまたはデータ通信を交換する目的でゲームによって作成される認証済みユーザーの、セキュリティで保護されたコレクション。 これは通常、ゲームのマルチプレイヤーセッションまたはチャット "ロビー" の概念に合わせて配置されます。
  • Endpoint -ネットワーク内でデータを送受信するための抽象化。 エンドポイントは、デバイス、ユーザー、または目的のゲーム固有の概念を表すことができます。
  • チャットコントロール-1 つ以上のネットワークで音声とテキストチャットを構成、発信、対象化するためのユーザーのための表現です。

オブジェクトのリレーションシップ

ネットワークには、シンプルな概念的階層として、ユーザー、オプションのエンドポイント、オプションのチャットコントロールが含まれているデバイスが含まれます。 次に例を示します。

簡素化された PlayFab パーティーのオブジェクト階層

以前のリレーションシップダイアグラムは不完全であるため、たとえば、複数のネットワークに接続されているデバイスについては、時間を経て複数のネットワークに接続するデバイスをサポートしています。たとえば、一連の大きなゲームセッションが相手との間でやり取りされることもあります。

複数のネットワークを使用すると、その機能を利用するように選択したゲームでは、微妙オブジェクトの関係が若干高くなります。 複数のネットワークのコンテキストで特定のインスタンスが検出されると、1つのリモートデバイス API オブジェクトのみが作成されます。

これにより、ゲームでは、ネットワーク上のデバイスについて、必要な最適化またはセキュリティの相関関係を実行できます。 また、PlayFab パーティー自体も、複数の可能なネットワーク接続がある場合でも、チャットコントロールのペア間でチャットデータを効率的かつ中断なしで送信できるように、社内で行われています。 そのため、デバイスまたはチャットコントロールオブジェクトを、概念的にはネットワークの "外部" として考えることができる場合があります。

例として、次の図は、ユーザー、チャットコントロール、エンドポイントが含まれる2つのネットワークと3つのデバイスを示しています。 デバイス aとその2つのチャットコントロール (関連付けられているユーザー) がネットワーク 1に参加していますが、デバイス BおよびCは、1つのチャットコントロール (および関連付けられたユーザー) によってネットワーク2とネットワーク 2の両方に接続されています。 すべてのデバイスは、接続されている各ネットワークに1つまたは2つのエンドポイントを作成しています。

複数のネットワークにおける PlayFab パーティーオブジェクト

上の図では、すべてのデバイスに、3つのデバイスとその両方の [チャットコントロール] が1つずつ表示されています。これは、互いに少なくとも1つのネットワークが共通しているためです。 デバイス aは、ネットワーク 1エンドポイント 1-4のみを認識します。ただし、デバイス BCでは、ネットワーク 2で作成されたエンドポイント 5-7も確認できます。

デバイス Cの代わりに、上の図のネットワーク 2にのみ参加し、両方のネットワークを対象としない場合は、次のようにします。

  • デバイス Cでは、ネットワーク 1エンドポイント 4は作成できなかったため、他のユーザーが作成したエンドポイント 1-3は表示されませんでした。
  • デバイス Cでは、ネットワーク 1デバイス Aまたはその2つのチャットコントロールについては認識されません。
  • デバイス Aにも同様に、ネットワーク 2ではデバイス Cやそのチャットコントロールしか表示されません。

ただし、デバイス B 両方のネットワークに存在するので、すべてのデバイスとそのチャットコントロールを表示することができます。

したがって、デバイスやチャットコントロールが、ネットワークとの厳格な階層構造のツリー関係にあるとしても、ゲームインスタンスが、対応するネットワークのコンテキストを使わずにリモートデバイスまたはチャットコントロールに実際に遭遇することはないことに注意することが重要です。 ローカルとリモートのデバイスまたはチャットコントロールに、少なくとも1つのネットワークが共通する場合は、リモートオブジェクトが表示されることがあります。 ただし、共通のネットワークがない場合、リモートオブジェクトは作成されません。

注意

PlayFab パーティーを正常に使用するために、ゲームは複数のネットワークに同時に接続する必要はありません。 複数のネットワークを使用するかどうかの詳細については、次の高度なトピックを参照してください。

一般的なオブジェクト属性

上記のすべてのオブジェクトには、適切に定義された有効期限があります。これは、ローカルのゲームインスタンスによって直接作成および破棄されます。または、ゲームの選択時にのみ通知される標準化された通知メカニズムを使っています。 通知を操作する方法については、後のトピックで詳しく説明します。

また、すべての PlayFab パーティー API オブジェクトは、カスタムコンテキストの概念をサポートします。これは、オプションのローカルのみの "ショートカット" ポインターまたは値をオブジェクトと共に格納するための手段です。 これにより、再生の非効率的な参照を実行せずに、簡単に再生することができるようになります。 ポインター値はローカルのゲームインスタンスにしか意味を持たないため、これらの値はリモートでは転送されません。

最後に、 network以外のすべてのオブジェクトには、オブジェクトを所有しているローカルデバイスのみが利用できるメソッドとプロパティを含む、専用の "ローカル" サブオブジェクトがあります。

たとえば、ローカルまたはリモートのPartyEndpoint エンドポイントを表すために使用される基底オブジェクトと、そのPartyLocalEndpointエンドポイントが実際にローカルPartyEndpoint::GetLocal()デバイスによって作成された場合にのみ取得できる、より具体的なオブジェクトがあります。

これは、1 PartyLocalEndpoint::SendMessage()つのデバイスでまったく異なるリモートデバイスのソースエンドポイントからデータを何らかの方法で伝送できるという意味ではないため、ゲームデータの送信方法を公開することです。

C++ PlayFab パーティーインターフェイス (推奨) を使う場合、オブジェクトは C++ クラスインスタンスとして公開されます。 フラット C インターフェイスを使う場合、オブジェクトはハンドル値で表されます。

主要なすべてのオブジェクトの役割について詳しく説明します。

  1. Manager (PartyManager)
  2. Network (PartyNetwork)
  3. デバイス(PartyDeviceおよびPartyLocalDevice)
  4. ユーザー (ユーザーエンティティ id およびPartyLocalUser)
  5. エンドポイントPartyEndpoint ( PartyLocalEndpointand)
  6. チャットコントロール(PartyChatControlおよびPartyLocalChatControl)
  7. 状態変更(PartyStateChange)

Manager

前に要約されているオブジェクトに加えて、PlayFab パーティー API でも最PartyManager上位レベルのシングルトンオブジェクトが公開されます。

この utility/組織オブジェクトは、他のオブジェクトの操作を開始するための出発点として使用されます。 ここでは、たとえば、新しいネットワークとローカルユーザーを最初に作成します。 すべての非同期操作の完了と通知は、ここでも一元管理されます。 おそらく基本的に、これは、PlayFab パーティーライブラリ自体を使用する前に初期化し、不要になったときにクリーンアップすることです。

Network

オブジェクトPartyNetworkは、参加しているデバイス、承認済みユーザー、関連するエンドポイントまたはチャットコントロールのセキュリティで保護されたコレクションを表します。 ネットワークは最初はゲームによって空として作成されますが、デバイスに接続して、少なくとも1つのローカルユーザーをネットワークに認証します。 認証されたユーザーがいないネットワークは、タイムアウト後に自動的に破棄されます。

ネットワークに接続するには、ネットワーク記述子を使ってネットワークを参照する必要があります。 これは、ネットワークを識別して特定するために、Playfab パーティーで内部的に必要な情報が含まれている、ほとんど不透明なバイナリ構造です。 API には、web サービスに対応した文字列に構造体をシリアル化するためのメソッドが用意されています。また、一般的なソーシャルプラットフォームの招待メカニズム、 Playfab マッチ、その他の外部ランデブーメカニズムを使って、他のデバイスと交換するには、Playfab パーティー自体の範囲外である必要があります。

注意

ネットワーク記述子は、まれnetworkな状況で変更される可能性があります。 このような変更を通知するためにゲームを準備して、既存のネットワークの新しいネットワーク記述子を更新または再アドバタイズして、接続されている追加のデバイスで問題が発生しないようにする必要があります。

ネットワーク記述子を利用できるようになっても、ネットワークへのアクセスは、特定のネットワークへの参加を事前に許可しているユーザーに制限されています (または、ユーザーが外部管理されているゲームプレイセッションに追加された場合は、"ジャストインタイム" となります)。 このユーザー認証は、ネットワーク作成中に実行され、詳細についてはトピック「招待状とセキュリティモデル」で詳しく説明するように、その後の作成と失効を行います。

ゲームでは、招待を使用して、ユーザーの友人のみにエントリを制限したり、悪意のあるプレーヤーがネットワークに参加できないようにしたりできます。

デバイスは、一度に複数のネットワークに接続できます。 複数のネットワークを使用するかどうかの詳細については、後のトピックを参照してください。

オブジェクトに対しPartyNetworkて実行できるアクションの種類には、ローカルユーザーの認証、チャットコントロールの接続と列挙、エンドポイントの作成と列挙、またはネットワーク全体のパフォーマンス情報の取得などがあります。

Device

このPartyDeviceオブジェクトは、ゲームの個別のインスタンスと、物理デバイスで実行されている Playfab パーティのライブラリコードを表します。 ほとんどの操作はオブジェクトPartyDevice自体では実行されません。このように、ユーザーは、そのゲームインスタンスに属するエンドポイントまたはチャットコントロール(特に複数のローカルユーザーを同時にサポートするプラットフォームとゲーム) を定義するための組織機構となります。 PlayFab パーティーは、この関係の知識を使用して、デバイス上の複数のターゲットから受信する必要がある場合でも、メッセージのコピーを1つだけ送信することで、ゲームデータとチャットの転送を最適化します。

リモートPartyDeviceオブジェクトは、ネットワークに接続し、そのネットワークでユーザーを認証する、"byproducts" です。 これは、有効な場合にのみ作成されるため、デバイスに関連付けられた認証済みのリモートユーザーは、ローカルデバイスにも接続されていて、それ以降は破棄されるネットワークに参加します。

一方、PlayFab パーティーがPartyLocalDevice初期化されている限り、ローカルゲームインスタンスでは常に、専用のサブオブジェクトを参照することができます。 これは、明示的に作成または破棄されることはありません。

ユーザー

Playfab パーティーのユーザーは、 title_player_account エンティティ IDとトークンを取得するために、ゲームがplayfab プレーヤーのログインを実行した一意のヒューマンプレーヤーです。 リモートユーザーは、PlayFab パーティ API 内で、チャットコントロールに関連付けられたエンティティ ID 文字列だけで識別されます。また、必要に応じてエンドポイントを使用することもできます。 専用のオブジェクトを使って表されるわけではありません。 これは、PlayFab パーティーには、生の識別以外の任意のユーザーとの意味を持つ、または他のオブジェクトに関連付けられたラベルとして、意味のある機能が備わっていないためです。

ただし、ローカルユーザー向けには、 PartyLocalUser Game が playfab パーティー内の有効期間を管理しているため、明示的なオブジェクトがあります。 通常、ゲームでは、 PartyLocalUserゲームが該当するログイン方法を使ってその playfab プレーヤーに正常にログインしたときPartyLocalUserに、そのユーザーがログオフするときに適切なものを破棄します。 複数のローカルプレイヤーをサポートするプラットフォームとゲームでは、 PartyLocalUser各プレーヤーに対して追加のオブジェクトを作成する必要があります。

PartyLocalUser オブジェクトは、すべての認証の基礎であるため、重要な要素でもあります。 新しいネットワークを作成する、または1つに認証するには、有効なローカルユーザーが存在している必要があります。

ユーザーの承認について詳しくは、「招待状とセキュリティモデル」をご覧ください。

ほとんどの操作ではPartyLocalUser 、オブジェクト自体にPartyLocalUser対して実行される操作が非常に少ない場合でも、を指定または表示する必要があります。

PartyLocalUser オブジェクトはPartyManagerオブジェクトを使って作成されます。 明示的に破棄できるのは、作成者だけです。 リモートデバイスに直接オブジェクト表現はありませんが、所有しているデバイスPartyLocalUserによってネットワークが切断された場合や接続が切断された場合に、関連付けられているチャットコントロールとエンドポイントは破棄されます。

エンドポイント

PartyEndpoint オブジェクトは任意ですが、それらを活用するゲームの PlayFab パーティデータ通信の中核となります。 エンドポイントは、一般的なネットワークソケットと同様に、ネットワーク内でデータメッセージを発信またはターゲット指定するための抽象化されたアドレッシングメカニズムです。 これは、メッセージの送受信を個別に識別するデバイス、個々のユーザー、または任意のゲームで定義された概念 (タンクユニットなど) を表すことができます。

専用PartyLocalEndpointサブオブジェクトは、ローカルゲームインスタンスによってネットワーク内で作成されたエンドポイント用です。 これは、ほとんどのエンドポイント機能が存在する場所です。 これPartyLocalEndpoint::SendMessage()は、のゲームデータペイPartyLocalEndpointロードを、同じネットワークPartyEndpoint内の1つ以上の他のオブジェクトに転送します。 インターネットパケットの損失 (配信の保証、注文など) を処理するのに最適な方法を選ぶためのさまざまなオプションが用意されています。低レイテンシ間のトレードオフを制御したり、同一または他のローカルエンドポイントの複数のメッセージを結合して、ゲームの送信速度をサポートしないようにしたりできます。 エンドポイントを使用したゲームデータの転送の詳細については、後のトピックを参照してください。

PartyEndpointオブジェクトには、データメッセージ自体のソースまたは送信先として、また、ネットワーク内の個別PartyEndpointのオブジェクトによって送受信されたメッセージペイロード内の特定のエンドポイントを参照できる、16ビットエンドポイントの一意識別子も割り当てられます。 これにより、独自のピアツーピア id のネゴシエーションを構築せずに、完全な大規模なユーザーエンティティ id文字列やその他の識別子を送信するオーバーヘッドを回避するための便利な方法が提供されます。

PartyLocalEndpoint オブジェクトは、そのPartyNetwork中のオブジェクトを使って作成されます。 これにより、 PartyEndpoint対応するオブジェクトがリモートデバイス上に作成されます。 エンドポイントは、作成者によって明示的に破棄することも、所有しているデバイスがネットワークから切断PartyLocalUserされるか (指定されていた場合)、関連付けられているオブジェクトがネットワークから削除された場合は、暗黙的に破棄されます。

チャットコントロール

PartyChatControl オブジェクトは、PlayFab パーティーのオプションのチャット通信機能を使用するためのメカニズムです。 これは、特定のユーザーに関連付けられたオーディオ入出力デバイス、基本設定、および通信ポリシーを表します。

専用PartyLocalChatControlのサブオブジェクトは、ローカルのゲームインスタンスによって作成されたチャットコントロールでも利用できます。 ここでは、たとえば、ネットワーク全体とチーム専用のチャットをPartyChatControl選択したり、プラットフォームポリシーの制限を適用したりするための、リモートオブジェクトとのチャットのアクセス許可を構成します。 地元のチャットコントロールは、チャットテキストの送信、音声の synthesizing を行うために使用されます。また、表記と音声ストリームの入力やミュートなどを行うことができます。

PartyLocalChatControl オブジェクトは、同じネットワーク内のリモートデバイス上のオブジェクトとPartyChatControlして作成される前に、ネットワークに接続されている必要があります。 デバイスとチャットコントロールが複数のネットワークにPartyChatControl接続されている場合でも、常に1つの代表オブジェクトしか表示されません。 これにより、音声とテキストチャットメッセージの不要な重複または中断を避けることができます。

PartyLocalChatControl オブジェクトは、包含PartyLocalDeviceオブジェクトを使って作成されます。 チャットコントロールの作成者によって明示的に破棄されることがあります。または、所有しているデバイスPartyLocalUserがネットワークから切断された場合や、関連付けられたオブジェクトがネットワークから削除された場合は、暗黙的に破棄されます。

状態の変更

PartyStateChange 構造体は、すべての非同期操作の完了、受信メッセージ、更新通知、およびその他の API 関連イベントをゲームに通知するために使用されます。

予期しないタイミングでインターネット経由の複雑なマルチマシン操作を操作する方法を簡単にするために、PlayFab パーティーは、ゲームによる明示的な呼び出しの結果としてではなく、API から報告される状態を変更しないことを保証します。 ただし、リモートで開始された操作や、ローカル状態、PlayFab パーティー、 PartyManager::StartProcessingStateChanges()およびPartyManager::FinishProcessingStateChanges()ゲームとの間の特別な組み合わせの方法を変更し、 これらの機能は、ゲームの作業ループのポイントで呼び出されます。このような更新を処理すると便利です。 新しいイベントは、0個PartyManager::StartProcessingStateChanges()以上PartyStateChangeの構造体の配列として報告されます。 ゲームで状態の変更が処理されると、配列はをPartyManager::FinishProcessingStateChanges()使って返されます。

構造PartyStateChange体は、単体では完全なオブジェクトではありません。 これは、特定の種類の入力や通知に関する情報、関連オブジェクトへのポインター、エラー情報が含まれる、より詳細な構造にキャストするベースヘッダーです。

状態変更の操作については、後のトピックで詳しく説明します。

次の手順